home *** CD-ROM | disk | FTP | other *** search
/ Suzy B Software 2 / Suzy B Software CD-ROM 2 (1994).iso / extras / programm / gemfsc19 / gemfsc19.lzh / GEMFAST.DOC < prev    next >
Text File  |  1993-05-15  |  324KB  |  10,825 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                                   GemFast v1.9 Beta
  29.  
  30.                         Public Domain GEM Programming Library
  31.                                     By Ian Lepore
  32.          
  33.         
  34.                                   Reference Manual
  35.         
  36.         
  37.  
  38.         
  39.         
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.        Contents
  72.  
  73.        Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . .    1
  74.           Quick Start Info . . . . . . . . . . . . . . . . . . . . . . .    1
  75.           Using this document  . . . . . . . . . . . . . . . . . . . . .    1
  76.           Begging for money  . . . . . . . . . . . . . . . . . . . . . .    2
  77.           Support  . . . . . . . . . . . . . . . . . . . . . . . . . . .    3
  78.  
  79.        Function Quick-Reference  . . . . . . . . . . . . . . . . . . . .    4
  80.  
  81.        Global Variables  . . . . . . . . . . . . . . . . . . . . . . . .    7
  82.           global[] . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  83.           gl_apversion . . . . . . . . . . . . . . . . . . . . . . . . .    7
  84.           gl_apcount . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  85.           gl_apid  . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  86.           gl_apprivate . . . . . . . . . . . . . . . . . . . . . . . . .    7
  87.           gl_apptree . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  88.           gl_ap1resv . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  89.           gl_aprshdr . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  90.           gl_ap2resv . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  91.           gl_grfhandle . . . . . . . . . . . . . . . . . . . . . . . . .    7
  92.           gl_rwdesk  . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  93.           gl_rfscrn  . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  94.           gl_hchar . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  95.           gl_h2char  . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  96.           gl_h4char  . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  97.           gl_h8char  . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  98.           gl_wchar . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  99.           gl_w2char  . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  100.           gl_w4char  . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  101.           gl_w8char  . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  102.           gl_wbox  . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  103.           gl_hbox  . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  104.           gl_vwout . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  105.           gl_vxout . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  106.  
  107.        Application Library . . . . . . . . . . . . . . . . . . . . . . .   10
  108.           apl_cleanup  . . . . . . . . . . . . . . . . . . . . . . . . .   11
  109.           apl_mmvectors  . . . . . . . . . . . . . . . . . . . . . . . .   12
  110.           apl_vclose . . . . . . . . . . . . . . . . . . . . . . . . . .   13
  111.           apl_vopen  . . . . . . . . . . . . . . . . . . . . . . . . . .   14
  112.           apl_vshared  . . . . . . . . . . . . . . . . . . . . . . . . .   15
  113.           apl_xexit  . . . . . . . . . . . . . . . . . . . . . . . . . .   16
  114.           appl_exit  . . . . . . . . . . . . . . . . . . . . . . . . . .   16
  115.           apl_xinit  . . . . . . . . . . . . . . . . . . . . . . . . . .   17
  116.           appl_init  . . . . . . . . . . . . . . . . . . . . . . . . . .   17
  117.  
  118.        Error Message Library . . . . . . . . . . . . . . . . . . . . . .   18
  119.           exterror . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
  120.           exterrset  . . . . . . . . . . . . . . . . . . . . . . . . . .   20
  121.  
  122.        Forms and Dialogs Library . . . . . . . . . . . . . . . . . . . .   22
  123.           Summary of Dialog Functions  . . . . . . . . . . . . . . . . .   22
  124.           Dialog Processing Options  . . . . . . . . . . . . . . . . . .   23
  125.  
  126.        
  127.        ======================================================================
  128.        GemFast v1.8                                                    Page i
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.              Basic Dialog Options  . . . . . . . . . . . . . . . . . . .   24
  138.              Dynamic Dialog Options  . . . . . . . . . . . . . . . . . .   25
  139.              Dynamic Dialog Defaults . . . . . . . . . . . . . . . . . .   26
  140.           Text and Button Formatting in Dynamic Dialogs  . . . . . . . .   26
  141.           frm_confine  . . . . . . . . . . . . . . . . . . . . . . . . .   28
  142.           frm_defaults . . . . . . . . . . . . . . . . . . . . . . . . .   29
  143.           frm_desktop  . . . . . . . . . . . . . . . . . . . . . . . . .   30
  144.           frm_dialog . . . . . . . . . . . . . . . . . . . . . . . . . .   32
  145.           frm_dsdial . . . . . . . . . . . . . . . . . . . . . . . . . .   35
  146.           frm_dsdialog . . . . . . . . . . . . . . . . . . . . . . . . .   35
  147.           frm_eflag  . . . . . . . . . . . . . . . . . . . . . . . . . .   37
  148.           frm_enableblit . . . . . . . . . . . . . . . . . . . . . . . .   39
  149.           frm_error  . . . . . . . . . . . . . . . . . . . . . . . . . .   40
  150.           frm_menu . . . . . . . . . . . . . . . . . . . . . . . . . . .   41
  151.           frm_mkmoveable . . . . . . . . . . . . . . . . . . . . . . . .   43
  152.           frm_nldialog . . . . . . . . . . . . . . . . . . . . . . . . .   44
  153.           frm_nlmenu . . . . . . . . . . . . . . . . . . . . . . . . . .   45
  154.           frm_printf . . . . . . . . . . . . . . . . . . . . . . . . . .   46
  155.           frm_progress . . . . . . . . . . . . . . . . . . . . . . . . .   47
  156.           frm_qchoice  . . . . . . . . . . . . . . . . . . . . . . . . .   50
  157.           frm_qerror . . . . . . . . . . . . . . . . . . . . . . . . . .   51
  158.           frm_qfatal . . . . . . . . . . . . . . . . . . . . . . . . . .   52
  159.           frm_qmenu  . . . . . . . . . . . . . . . . . . . . . . . . . .   53
  160.           frm_qtext  . . . . . . . . . . . . . . . . . . . . . . . . . .   54
  161.           frm_question . . . . . . . . . . . . . . . . . . . . . . . . .   55
  162.           frm_sizes  . . . . . . . . . . . . . . . . . . . . . . . . . .   56
  163.           frm_verror . . . . . . . . . . . . . . . . . . . . . . . . . .   57
  164.           frm_vprintf  . . . . . . . . . . . . . . . . . . . . . . . . .   57
  165.           frm_vprogres . . . . . . . . . . . . . . . . . . . . . . . . .   57
  166.  
  167.        File Selector Library . . . . . . . . . . . . . . . . . . . . . .   58
  168.           fsel_exinput . . . . . . . . . . . . . . . . . . . . . . . . .   59
  169.           fsel_sminput . . . . . . . . . . . . . . . . . . . . . . . . .   60
  170.           fsl_dialog . . . . . . . . . . . . . . . . . . . . . . . . . .   61
  171.  
  172.        Graphics Library  . . . . . . . . . . . . . . . . . . . . . . . .   64
  173.           gra_qmstate  . . . . . . . . . . . . . . . . . . . . . . . . .   65
  174.           gra_qofmouse . . . . . . . . . . . . . . . . . . . . . . . . .   65
  175.           gra_qonmouse . . . . . . . . . . . . . . . . . . . . . . . . .   65
  176.           grf_blit . . . . . . . . . . . . . . . . . . . . . . . . . . .   66
  177.           grf_memblit  . . . . . . . . . . . . . . . . . . . . . . . . .   68
  178.           graf_mouse . . . . . . . . . . . . . . . . . . . . . . . . . .   69
  179.           grf_mouse  . . . . . . . . . . . . . . . . . . . . . . . . . .   69
  180.  
  181.        Menu Library  . . . . . . . . . . . . . . . . . . . . . . . . . .   71
  182.           menu_bar . . . . . . . . . . . . . . . . . . . . . . . . . . .   72
  183.           mnu_bar  . . . . . . . . . . . . . . . . . . . . . . . . . . .   72
  184.           mnu_disable  . . . . . . . . . . . . . . . . . . . . . . . . .   73
  185.           mnu_enable . . . . . . . . . . . . . . . . . . . . . . . . . .   74
  186.           mnu_erase  . . . . . . . . . . . . . . . . . . . . . . . . . .   75
  187.           mnu_tbar . . . . . . . . . . . . . . . . . . . . . . . . . . .   76
  188.  
  189.        Object Library  . . . . . . . . . . . . . . . . . . . . . . . . .   77
  190.           obj_bmbuttons  . . . . . . . . . . . . . . . . . . . . . . . .   78
  191.  
  192.        
  193.        ======================================================================
  194.        GemFast v1.8                                                   Page ii
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.           obj_clcalc . . . . . . . . . . . . . . . . . . . . . . . . . .   81
  204.           obj_flchange . . . . . . . . . . . . . . . . . . . . . . . . .   82
  205.           obj_gstring  . . . . . . . . . . . . . . . . . . . . . . . . .   83
  206.           obj_gtype  . . . . . . . . . . . . . . . . . . . . . . . . . .   84
  207.           obj_gvalue . . . . . . . . . . . . . . . . . . . . . . . . . .   85
  208.           obj_offxywh  . . . . . . . . . . . . . . . . . . . . . . . . .   86
  209.           obj_parent . . . . . . . . . . . . . . . . . . . . . . . . . .   87
  210.           obj_ppstring . . . . . . . . . . . . . . . . . . . . . . . . .   88
  211.           obj_rbfind . . . . . . . . . . . . . . . . . . . . . . . . . .   89
  212.           obj_rbselect . . . . . . . . . . . . . . . . . . . . . . . . .   90
  213.           obj_sstring  . . . . . . . . . . . . . . . . . . . . . . . . .   91
  214.           obj_stchange . . . . . . . . . . . . . . . . . . . . . . . . .   92
  215.           obj_svalue . . . . . . . . . . . . . . . . . . . . . . . . . .   93
  216.           obj_xtfind . . . . . . . . . . . . . . . . . . . . . . . . . .   94
  217.           obj_xywh . . . . . . . . . . . . . . . . . . . . . . . . . . .   95
  218.  
  219.        Miscellanious Utilities Library . . . . . . . . . . . . . . . . .   96
  220.           rc_confine . . . . . . . . . . . . . . . . . . . . . . . . . .   97
  221.           rc_copy  . . . . . . . . . . . . . . . . . . . . . . . . . . .   98
  222.           rc_equal . . . . . . . . . . . . . . . . . . . . . . . . . . .   99
  223.           rc_gadjust . . . . . . . . . . . . . . . . . . . . . . . . . .  100
  224.           rc_gtov  . . . . . . . . . . . . . . . . . . . . . . . . . . .  101
  225.           rc_intersect . . . . . . . . . . . . . . . . . . . . . . . . .  102
  226.           rc_ptinrect  . . . . . . . . . . . . . . . . . . . . . . . . .  103
  227.           rc_scale . . . . . . . . . . . . . . . . . . . . . . . . . . .  104
  228.           rc_union . . . . . . . . . . . . . . . . . . . . . . . . . . .  105
  229.           rc_vadjust . . . . . . . . . . . . . . . . . . . . . . . . . .  106
  230.           rc_vtog  . . . . . . . . . . . . . . . . . . . . . . . . . . .  107
  231.           RECTARRAY  . . . . . . . . . . . . . . . . . . . . . . . . . .  108
  232.           RECTPTRS . . . . . . . . . . . . . . . . . . . . . . . . . . .  109
  233.           RECTVALS . . . . . . . . . . . . . . . . . . . . . . . . . . .  110
  234.           wc_scroll_calc . . . . . . . . . . . . . . . . . . . . . . . .  111
  235.  
  236.        Resource Library  . . . . . . . . . . . . . . . . . . . . . . . .  112
  237.           rsc_cubuttons  . . . . . . . . . . . . . . . . . . . . . . . .  113
  238.           rsc_gstrings . . . . . . . . . . . . . . . . . . . . . . . . .  114
  239.           rsc_gtrees . . . . . . . . . . . . . . . . . . . . . . . . . .  116
  240.           rsc_rrbuttons  . . . . . . . . . . . . . . . . . . . . . . . .  117
  241.           rsc_sstrings . . . . . . . . . . . . . . . . . . . . . . . . .  118
  242.           rsc_sxtypes  . . . . . . . . . . . . . . . . . . . . . . . . .  120
  243.           rsc_treefix  . . . . . . . . . . . . . . . . . . . . . . . . .  121
  244.  
  245.        Window Library  . . . . . . . . . . . . . . . . . . . . . . . . .  122
  246.           wnd_top  . . . . . . . . . . . . . . . . . . . . . . . . . . .  123
  247.           wind_update  . . . . . . . . . . . . . . . . . . . . . . . . .  124
  248.           wnd_update . . . . . . . . . . . . . . . . . . . . . . . . . .  124
  249.  
  250.        Extended Binding Functions  . . . . . . . . . . . . . . . . . . .  125
  251.           evnx_multi . . . . . . . . . . . . . . . . . . . . . . . . . .  126
  252.           frmx_center  . . . . . . . . . . . . . . . . . . . . . . . . .  127
  253.           frmx_dial  . . . . . . . . . . . . . . . . . . . . . . . . . .  128
  254.           grfx_dragbox . . . . . . . . . . . . . . . . . . . . . . . . .  129
  255.           winx_calc  . . . . . . . . . . . . . . . . . . . . . . . . . .  130
  256.           winx_get . . . . . . . . . . . . . . . . . . . . . . . . . . .  131
  257.  
  258.        
  259.        ======================================================================
  260.        GemFast v1.8                                                  Page iii
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.        Extended VDI Functions  . . . . . . . . . . . . . . . . . . . . .  132
  270.           vdicall  . . . . . . . . . . . . . . . . . . . . . . . . . . .  133
  271.           vgd_detect . . . . . . . . . . . . . . . . . . . . . . . . . .  134
  272.           vg_gdos  . . . . . . . . . . . . . . . . . . . . . . . . . . .  134
  273.           v_gchar  . . . . . . . . . . . . . . . . . . . . . . . . . . .  135
  274.  
  275.        Extended Object Library . . . . . . . . . . . . . . . . . . . . .  136
  276.           Background . . . . . . . . . . . . . . . . . . . . . . . . . .  136
  277.           Using Extended Objects . . . . . . . . . . . . . . . . . . . .  137
  278.           xob_nslide_change  . . . . . . . . . . . . . . . . . . . . . .  139
  279.           xob_nslide_create  . . . . . . . . . . . . . . . . . . . . . .  140
  280.           xob_nslide_get . . . . . . . . . . . . . . . . . . . . . . . .  142
  281.           xob_nslide_set . . . . . . . . . . . . . . . . . . . . . . . .  143
  282.           xob_thermo_change  . . . . . . . . . . . . . . . . . . . . . .  144
  283.           xob_thermo_create  . . . . . . . . . . . . . . . . . . . . . .  145
  284.           xob_thermo_update  . . . . . . . . . . . . . . . . . . . . . .  147
  285.           xob_tscroll_create . . . . . . . . . . . . . . . . . . . . . .  149
  286.           xob_tscroll_get  . . . . . . . . . . . . . . . . . . . . . . .  151
  287.           xob_tscroll_set  . . . . . . . . . . . . . . . . . . . . . . .  152
  288.  
  289.        Extended Object Developer's Guide . . . . . . . . . . . . . . . .  155
  290.           xob_draw . . . . . . . . . . . . . . . . . . . . . . . . . . .  156
  291.           xob_transform  . . . . . . . . . . . . . . . . . . . . . . . .  158
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.        
  325.        ======================================================================
  326.        GemFast v1.8                                                   Page iv
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.        Introduction
  336.  
  337.  
  338.                  Welcome to version 1.9 of GemFast, the public domain GEM
  339.                  bindings and programming library.
  340.  
  341.                  The primary changes in v1.9 are concerned with portability
  342.                  to most existing ST compilers.  The source code and header
  343.                  files now use ANSI function prototypes when the host
  344.                  compiler supports them.
  345.  
  346.                  The other major change is the consistent use of 'short'
  347.                  rather than 'int' in the GEM interface.  This became an
  348.                  issue with compilers (such as GNU C and Lattice C) that
  349.                  support both 16-bit and 32-bit integer sizes.  The Lattice C
  350.                  compiler (which Atari itself now uses) has low-level GEM
  351.                  bindings that use the 'short' datatype consistently, so
  352.                  GemFast has adopted this convention.  You may experience a
  353.                  few pointer type mismatches if you're using an ANSI
  354.                  compiler, but these are (in my experience anyway) quickly
  355.                  fixed in your source code by changing int* to short*.
  356.  
  357.  
  358.             Quick Start Info
  359.  
  360.  
  361.                  Because you generally only need it once, the installation
  362.                  instructions, packing list, technical notes, and portability
  363.                  notes are in a separate file called GEMFINST.DOC.  
  364.  
  365.                  If you're installing for the first time, GEMFINST.DOC has
  366.                  all the info you need to install the GemFast files on your
  367.                  system.  If you got GemFast along with the HSC compiler, the
  368.                  INSTALL program has already installed GemFast for you, but
  369.                  you should still review GEMFINST.DOC.
  370.  
  371.                  If you're upgrading from a prior release, you'll find the
  372.                  installation process pretty much the same as usual.
  373.  
  374.  
  375.             Using this document
  376.  
  377.  
  378.                  This document, as delivered, is formatted for printing on
  379.                  virtually any printer.  The format is a compromise between
  380.                  one that prints reasonably well on any type of printer, and
  381.                  one that is easy to browse interactively with an editor. 
  382.                  The original document is formatted very nicely indeed, in WP
  383.                  5.1 (MSDOS) format.  I'll distribute that version too, if
  384.                  anyone asks for it.
  385.  
  386.                  Here are some hints for online viewing...  If you're looking
  387.                  for a particular function, do a search on its name.  You'll
  388.                  find the entry in the table of contents.  If you just need a
  389.  
  390.        
  391.        ======================================================================
  392.        GemFast v1.8                                                    Page 1
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.                  reminder of the function parameters, do a 'repeat search',
  402.                  and you'll find the prototype in the Quick Reference
  403.                  chapter.  If you want the full details of for the function,
  404.                  note the page number when you find the function in the table
  405.                  of contents, then do a search for "Page ##" to get near the
  406.                  function.  Then back up a few lines (page numbers are at the
  407.                  bottom of each page) to find the function.
  408.  
  409.                  This rather complex search-for-the-page-number nonsense is
  410.                  needed because the function descriptions include cross
  411.                  references and you could end up doing 20 or 30 'repeat
  412.                  search' operations on the function name to get to the actual
  413.                  description.  I hope to write a hypertext-like browser
  414.                  accessory for these docs soon to make this problem go away.
  415.  
  416.                  In the function descriptions, the last item is always a line
  417.                  stating where the source code for the file is found. 
  418.                  Because function descriptions cross page boundaries, be sure
  419.                  to keep reading until you hit the Source: line.
  420.  
  421.  
  422.             Begging for money
  423.  
  424.  
  425.                  Yes, after almost five years of distributing GemFast with no
  426.                  strings attached, I've suddenly become mercenary.  It has
  427.                  something to do with being unemployed at the moment. 
  428.  
  429.                  If you like GemFast, and you feel generous, please send a
  430.                  contribution of $15 to the name and address listed under
  431.                  Support, below.  Please do not send currency in the mail, it
  432.                  encourages crime.  If you are outside of the U.S.A., please
  433.                  don't feel obligated to send a contribution; it's more
  434.                  trouble than it's worth for you folks to get a check payable
  435.                  in US funds.
  436.  
  437.                  Despite my begging for contributions, GemFast is not
  438.                  shareware, it is public domain.  Here's the deal...
  439.  
  440.                    - GemFast v1.9 is 100% Public Domain.  I hereby explicitly
  441.                      release all rights to GemFast v1.9; you can use and
  442.                      distribute the source and binary in any way you like.  
  443.  
  444.                    - Programs developed with GemFast can be copyrighted by
  445.                      you or another party as you see fit; my release of
  446.                      rights to GemFast is not to be construed as a release of
  447.                      rights for any work which contains GemFast functions.
  448.  
  449.                    - Please keep the distribution archives completely intact
  450.                      when copying GemFast to other BBS systems.  If you've
  451.                      used GemFast as the GEM support for a compiler, you can
  452.                      package the files with your compiler as you wish.  (IE,
  453.                      if you're just copying the standard distribution, please
  454.                      do it my way.  If you've repackaged as part of a larger
  455.  
  456.        
  457.        ======================================================================
  458.        GemFast v1.8                                                    Page 2
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.                      work under another name, do it however you want.)
  468.  
  469.  
  470.             Support
  471.  
  472.  
  473.                  I love to hear from you, but I don't promise personalized
  474.                  replies.  I do take seriously all input I get on GemFast.
  475.  
  476.                  The files AES_VRSN.DOC and VDI_VRSN.DOC contain cumulative
  477.                  revision notes.  If you had only reported it, *your*
  478.                  favorite bug or enhancement might have been listed there.
  479.  
  480.                  Please don't hesitate to send me bug reports, suggestions
  481.                  for enhancements, or code you've written.  Look through your
  482.                  existing programs...if there are functions that show up in a
  483.                  lot of them, chances are they'd be at home in the GemFast
  484.                  libraries, so send them along.  A $15 contribution won't be
  485.                  refused either.  
  486.  
  487.                  I can be reached on the BIX online system, as "ianl".  Via
  488.                  internet, I can be reached at ianl@bix.com.  Questions that
  489.                  you think might be of general interest can be posted on
  490.                  usenet in comp.sys.atari.st.tech.  (This is the only usenet
  491.                  newsgroup I read; don't post in the other atari newsgroups
  492.                  if you expect me to reply.)  You can also reach me by snail-
  493.                  mail, at:
  494.  
  495.                      Ian Lepore
  496.                      6762 Marshall St.
  497.                      Arvada, CO  80003-4030
  498.                      USA
  499.  
  500.                  I probably won't reply by snail-mail, because my printer is
  501.                  broken (and there's not a chance of my writing a letter
  502.                  longhand).  If you reach me electronically, I'll generally
  503.                  reply within a few days.
  504.  
  505.                  - Ian Lepore
  506.                    05/05/93
  507.                    ianl@bix.com          (preferred email address)
  508.                    ilepore@nyx.cs.du.edu (use this if bix.com fails)
  509.                    Moderator, BIX atari.st and c.language conferences
  510.                    Independent Software Developer (read: unemployed)
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.        
  523.        ======================================================================
  524.        GemFast v1.8                                                    Page 3
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.        Function Quick-Reference
  534.  
  535.  
  536.                  If you're like me, half the times you look at a library doc
  537.                  it's because you've forgotten what order the parms are in
  538.                  for some function.  Here's a list of prototypes for all
  539.                  functions.  Full descriptions of each function can be found
  540.                  in later chapters.
  541.  
  542.        void   apl_cleanup(short cleanup_type);
  543.        void   apl_mmvectors(void *allocfunc, void *freefunc);
  544.        void   apl_vclose(short vhandle);
  545.        short  apl_vopen(void);
  546.        short  apl_vshared(void);
  547.        void   apl_xexit(void);
  548.        short  apl_xinit(void);
  549.        char  *exterror(short errcode);
  550.        short  exterrset(_Err_tab *msgtab, short install_or_remove);
  551.        void   frm_confine(OBJECT *tree, GRECT *boundrect);
  552.        long   frm_defaults(long options);
  553.        void   frm_desktop(long options, OBJECT *tree);
  554.        short  frm_dialog(long options, OBJECT *tree, short editobj);
  555.        short  frm_dsdialog(long options, char **btnarray, char **strarray);
  556.        short  frm_dsmenu(long options, char *title, char **itemarray);
  557.        short  frm_eflag(OBJECT *tree, short object, char *fmt, ...);
  558.        void   frm_enableblit(void);
  559.        short  frm_error(short errcode, char *buttons, char *fmt, ...);
  560.        short  frm_menu(long options, OBJECT *tree, short select_state);
  561.        short  frm_mkmoveable(OBJECT *tree, short mover_object);
  562.        short  frm_nldialog(long options, char *buttons, char *lines);
  563.        short  frm_nlmenu(long options, char *title, char *items);
  564.        short  frm_printf(long options, char *buttons, char *fmt, ...);
  565.        short  frm_progress(long options, short increments, char *abortbutton,
  566.                            char *fmt, ...);
  567.        short  frm_qchoice(char *buttons, char *fmt, ...);
  568.        short  frm_qerror(short error, char *fmt, ...);
  569.        short  frm_qmenu(char *title, char *selections);
  570.        void   frm_qtext(char *fmt, ...);
  571.        short  frm_question(char *fmt, ...);
  572.        void   frm_sizes(OBJECT *tree, GRECT *outrect);
  573.        short  frm_verror(short errcode, char *buttons, char *fmt, 
  574.                          va_list args);
  575.        short  frm_vprintf(long options, char *buttons, char *fmt, 
  576.                           va_list args);
  577.        short  fsl_dialog(short options, char *opath, char *ipath, 
  578.                          char *forcewild, char *prompt);
  579.        long   grf_blit(short options, void *buffer, void *rect_or_tree);
  580.        void  *grf_memblit(short options, void *buffer, void *rect_or_tree);
  581.        short  grf_mouse(short newshape, void *usershape);
  582.        short  mnu_bar(OBJECT *tree, short install_or_remove, long reserved);
  583.        void   mnu_disable(void);
  584.        void   mnu_enable(void);
  585.        void   mnu_erase(void);
  586.        void   mnu_tbar(char *title_string);
  587.  
  588.        
  589.        ======================================================================
  590.        GemFast v1.8                                                    Page 4
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.        short  obj_bmbuttons(OBJECT *tree, short parent, short select_state, 
  600.                             short bitmap);
  601.        short  obj_clcalc(OBJECT *tree, short object, GRECT *grectout, 
  602.                          VRECT *vrectout);
  603.        void   obj_flchange(OBJECT *tree, short object, short newstate, 
  604.                            int redraw, ...);
  605.        void   obj_offxywh(OBJECT *tree, short object, GRECT *outrect);
  606.        short  obj_parent(OBJECT *tree, short object);
  607.        char **obj_ppstring(OBJECT *pobj);
  608.        short  obj_rbfind(OBJECT *tree, short parent, short select_state);
  609.        short  obj_rbselect(OBJECT *tree, short object, short select_state);
  610.        void   obj_stchange(OBJECT *tree, short object, short new_state, 
  611.                            int redraw, ...);
  612.        short  obj_xtfind(OBJECT *tree, short parent, short select_state);
  613.        void   obj_xywh(OBJECT *tree, short object, GRECT *outrect);
  614.        void   rc_confine(GRECT *boundrect, GRECT *therect);
  615.        void   rc_copy(GRECT *source, GRECT *dest);
  616.        int    rc_equal(GRECT *rect1, GRECT *rect1);
  617.        GRECT *rc_gadjust(GRECT *dest, short hadjust, short vadjust);
  618.        VRECT *rc_gtov(GRECT *source, VRECT *dest);
  619.        int    rc_intersect(GRECT *source, GRECT *dest);
  620.        short  rc_ptinrect(GRECT *therect, short x, short y);
  621.        GRECT *rc_scale(GRECT *source, GRECT *dest, short percentage);
  622.        void   rc_union(GRECT *source, GRECT *dest);
  623.        VRECT *rc_vadjust(VRECT *dest, short hadjust, short vadjust);
  624.        GRECT *rc_vtog(VRECT *source, GRECT *dest);
  625.        short  rsc_cubuttons(OBJECT *tree);
  626.        void   rsc_gstrings(OBJECT *tree, int object, char **ppstring, ...);
  627.        void   rsc_gtrees(int object, OBJECT **pptree, ...);
  628.        short  rsc_rrbuttons(OBJECT *tree);
  629.        void   rsc_sstrings(OBJECT *tree, int object, char *string, ...);
  630.        void   rsc_sxtypes(OBJECT *tree, int object, int xtype, ...);
  631.        void   rsc_treefix(OBJECT *tree);
  632.        short  wnd_top(void);
  633.        short  wnd_update(short semaphore);
  634.        void   xob_nslide_change(OBJECT *tree, short object, long newmin, 
  635.                              long newmax)
  636.        short  xob_nslide_create(OBJECT *tree, short object, long min, 
  637.                              long max)
  638.        long   xob_nslide_get(OBJECT *tree, short object)
  639.        void   xob_nslide_set(OBJECT *tree, short object, long newvalue)
  640.        short  xob_thermo_change(OBJECT *tree, short object, 
  641.                              short increments);
  642.        short  xob_thermo_create(OBJECT *tree, short object,
  643.                              short increments);
  644.        short  xob_thermo_update(OBJECT *tree, short object, 
  645.                              short newpos, GRECT *cliprect);
  646.        void   xob_transform(XUSERBLK *xub, OBJECT *pobject, void *drawfunc);
  647.  
  648.        short  evnx_multi(XMULTI *xm);
  649.        short  frmx_center(OBJECT *tree, GRECT *outrect);
  650.        short  frmx_dial(short flag, GRECT *little, GRECT *big);
  651.        short  grfx_dragbox(GRECT *start, GRECT *boundary, GRECT *end);
  652.        short  winx_calc(short type, short kind, GRECT inrect, GRECT
  653.  
  654.        
  655.        ======================================================================
  656.        GemFast v1.8                                                    Page 5
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.                         *outrect);
  666.        short  winx_get(short whandle, short field, GRECT *outrect);
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.        
  721.        ======================================================================
  722.        GemFast v1.8                                                    Page 6
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.        Global Variables
  732.  
  733.  
  734.                  GemFast provides several global variables containing
  735.                  information about the state of the system and your
  736.                  application.  The GEMFAST.H header file declares all these
  737.                  variables; you can just refer to them as needed in your
  738.                  programs.  When using compilers other than HSC or GNU C, the
  739.                  names below are still valid; macros in GEMFAST.H alias the
  740.                  names below to the actual names used by the compiler's low-
  741.                  level bindings.  A summary of the variables appears below,
  742.                  followed by detailed information about them.
  743.  
  744.                  The following variables are defined by GEM:   
  745.  
  746.                    short  global[];      also aliased by following names...
  747.                    short  gl_apversion;  the AES version number
  748.                    short  gl_apcount;    max # of concurrent AES applications
  749.                    short  gl_apid;       id of the current application
  750.                    long   gl_apprivate;  anything application wants to store 
  751.                    void  *gl_apptree;    pointer to array of object tree ptrs
  752.                    long   gl_ap1resv;    old name for pointer to rsc data
  753.                    RSHDR *gl_aprshdr;    pointer to head of rsc data
  754.                    short  gl_ap2resv[6]; unused entries in global array
  755.  
  756.                  The following variables are defined by GemFast:
  757.  
  758.                    short  gl_grfhandle;  physical VDI workstation handle 
  759.                    GRECT  gl_rwdesk;     coordinates of the desktop workarea
  760.                    GRECT  gl_rfscrn;     coordinates of the full screen
  761.                    short  gl_hchar;      height of a character
  762.                    short  gl_h2char;     height of a character divided by 2
  763.                    short  gl_h4char;     height of a character divided by 4
  764.                    short  gl_h8char;     height of a character divided by 8
  765.                    short  gl_wchar;      width of a character
  766.                    short  gl_w2char;     width of a character divided by 2
  767.                    short  gl_w4char;     width of a character divided by 4
  768.                    short  gl_w8char;     width of a character divided by 8
  769.                    short  gl_wbox;       width of a boxchar
  770.                    short  gl_hbox;       height of a boxchar
  771.  
  772.                  The following variables are valid only after one or more
  773.                  calls have been made to apl_vopen() or apl_vshared():
  774.  
  775.                    short  gl_vwout[57];  the work_out from v_opnvwk()
  776.                    short  gl_vxout[57];  the work_out from vq_extnd(,1,)
  777.  
  778.                  The GEM-defined variables are documented in any manual or
  779.                  textbook on GEM programming.  The gl_ names in this group
  780.                  are just aliases for the items in the global array.  (That
  781.                  is, gl_apversion is just another name for global[0], etc.)
  782.  
  783.                  The GemFast-defined variables contain data that many GemFast
  784.                  library routines (and GEM programs in general) need frequent
  785.  
  786.        
  787.        ======================================================================
  788.        GemFast v1.8                                                    Page 7
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.                  access to.  You can refer to these values in your code any
  798.                  time after you've called appl_init().  The values in these
  799.                  variables will never change, and you must never change them;
  800.                  they are for reference only.
  801.  
  802.                  The gl_grfhandle variable contains the physical VDI
  803.                  workstation handle owned by the AES.  This is the value
  804.                  returned by graf_handle().  You should never use this handle
  805.                  directly in your VDI calls; the only proper use is to pass
  806.                  this value to VDI when opening a virtual screen workstation.
  807.  
  808.                  The gl_wchar, gl_hchar, gl_wbox, and gl_hbox variables
  809.                  contain the sizes of a character and a box that will hold a
  810.                  character.  These are the values returned by graf_handle(). 
  811.                  They are very useful values, please use them whenever you
  812.                  can instead of hard-coding size constants (which may be
  813.                  wrong when alternate monitors are in use).  The variables in
  814.                  this group that have 2, 4, and 8 in the name are useful for
  815.                  creating resolution-independent fine alignments when you
  816.                  dynamically construct or modify objects at runtime.  
  817.  
  818.                  The gl_rwdesk structure contains the xywh values that
  819.                  describe the work area of the desktop (everything on the
  820.                  screen except the menu bar area, generally).  The gl_rfscrn
  821.                  structure contains the xywh values that describe the full
  822.                  screen.  These values can be handy for clipping and
  823.                  confining operations; just pass their address (don't forget
  824.                  the '&' character!) to the rectangle calculation functions
  825.                  as needed.
  826.  
  827.                  The gl_vwout array contains the values that v_opnvwk() puts
  828.                  into the work_out array.  The gl_vxout array contains the
  829.                  values from vq_extnd(handle, 1, gl_vxout).  The values in
  830.                  these two arrays are valid only after you've opened a VDI
  831.                  workstation by calling apl_vopen().  These arrays are
  832.                  defined in a different module than the other global
  833.                  variables, and will only be linked into your program if you
  834.                  actually use VDI (or use a GemFast function which uses VDI).
  835.  
  836.                  Some of the variables are defined and initialized by GEM
  837.                  during the appl_init() call, and others are defined and
  838.                  initialized by GemFast during the apl_xinit() call.  A macro
  839.                  in GEMFAST.H remaps your existing appl_init() calls through
  840.                  the new apl_xinit().  Do NOT undo this mapping macro!  The
  841.                  GemFast library routines count on the data in the global
  842.                  variables being accurate, and that will only happen if
  843.                  control was passed through apl_xinit() on the way to the
  844.                  real GEM init function.
  845.  
  846.                  In general, I don't like global variables in C programs very
  847.                  much.  But, as the GemFast library routines became more
  848.                  complex, I found that every new routine was calling GEM to
  849.                  get the height of a character or the rectangle describing
  850.                  the system desktop or something.  It was getting to be a
  851.  
  852.        
  853.        ======================================================================
  854.        GemFast v1.8                                                    Page 8
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.                  real performance problem.  So, I looked back through five
  864.                  years worth of programs I've written, and decided on a small
  865.                  set of global variables to hold the information that most
  866.                  GEM programs seem to need.  Note that all of these variables
  867.                  are items that you should consider as being read-only in
  868.                  nature.  (Somehow I feel that helps justify their existence
  869.                  as global variables.)
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.        
  919.        ======================================================================
  920.        GemFast v1.8                                                    Page 9
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.        Application Library
  930.  
  931.  
  932.                  Application library routines provide an interface between
  933.                  your program and the host environments that can supply
  934.                  services and resources to you.  Those hosts include GemFast
  935.                  itself, the GEM VDI and AES, and GEMDOS.  In general,
  936.                  application library routines help you manage system
  937.                  resources.
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.        
  985.        ======================================================================
  986.        GemFast v1.8                                                   Page 10
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.        void apl_cleanup(short options)
  996.        ______________________________________________________________________
  997.  
  998.        Summary:  Cleanup resources acquired internally by other library
  999.                  routines.
  1000.  
  1001.        Input:    The options parameter specifies the type of resources to
  1002.                  clean up.  OR together any of the following:
  1003.  
  1004.                    APL_RTRANSIENT -  Temporary resources, such as the shared
  1005.                                      VDI workstation.
  1006.                    APL_RPERMANENT -  Permanent resources, such as attachments
  1007.                                      to RSC data.
  1008.  
  1009.        Returns:  Nothing.
  1010.  
  1011.        See also: apl_xexit()
  1012.  
  1013.        Details:  Some library routines acquire system resources (VDI handle,
  1014.                  blocks of memory, etc) in the course of processing.  This
  1015.                  function releases those resources.  
  1016.  
  1017.                  This is intended primarily for desk accessories.  When an
  1018.                  AC_CLOSE message is received, call this function with a 
  1019.                  flag value of APL_RTRANSIENT.  If the desk accessory is
  1020.                  going to unload itself, or has detected that a resolution
  1021.                  change is happening, call this function with a flag value of
  1022.                  (APL_RTRANSIENT | APL_RPERMANENT).
  1023.  
  1024.                  For a non-accessory program, a cleanup happens automatically
  1025.                  when you call appl_exit(); you don't need to call
  1026.                  apl_cleanup() explicitly.
  1027.  
  1028.                  Right now, the only transient resource is the shared VDI
  1029.                  workstation, and there are no permanent resources.  That
  1030.                  will change soon.
  1031.  
  1032.        Source:   aesfuncs\aplxinit.c
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.        
  1051.        ======================================================================
  1052.        GemFast v1.8                                                   Page 11
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.        void apl_mmvectors(void *allocfunc, void *freefunc)
  1062.        ______________________________________________________________________
  1063.  
  1064.        Summary:  Specify the memory management routines for GemFast library
  1065.                  functions to use when they need to allocate memory.
  1066.  
  1067.        Input:    The allocfunc parameter is a pointer to a memory allocation
  1068.                  routine.
  1069.  
  1070.                  The freefunc parameter is a pointer to the memory free
  1071.                  routine associated with the allocfunc allocation routine.
  1072.  
  1073.        Returns:  Nothing.
  1074.  
  1075.        See also:
  1076.  
  1077.        Details:  Some GemFast library routines need to allocate and free
  1078.                  blocks of memory.  By default, your compiler's runtime
  1079.                  library allocation functions (malloc, lalloc, free) will be
  1080.                  used.
  1081.  
  1082.                  The most common use of this function will be to supply your
  1083.                  own memory allocation functions, for debugging or better
  1084.                  performance or whatever.  The allocation function must
  1085.                  accept a longword parameter and return a 32-bit pointer. 
  1086.                  Often this function is called lalloc() or farmalloc() in
  1087.                  your compiler library.  So the most common use would look
  1088.                  like this:
  1089.  
  1090.                      apl_mmvectors(lalloc, free);
  1091.  
  1092.                  If you want to write your own memory management functions,
  1093.                  here are some rules...  The allocator has to accept a
  1094.                  longword size parameter, and return a 32-bit pointer.  It
  1095.                  returns NULL if the memory can't be allocated.  The free
  1096.                  function has to accept a 32-bit pointer; it returns nothing. 
  1097.                  Do NOT write an 'intercept' allocator that accepts a
  1098.                  longword size and passes it along to malloc() as a 16-bit
  1099.                  value.  A huge moveable dialog box could occupy more than
  1100.                  64k of screen memory on a high-resolution system.
  1101.  
  1102.        Source:   aesfuncs\aplmallo.c
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.        
  1117.        ======================================================================
  1118.        GemFast v1.8                                                   Page 12
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.        void apl_vclose(short vdi_handle)
  1128.        ______________________________________________________________________
  1129.  
  1130.        Summary:  Close a VDI workstation opened with apl_vopen().
  1131.  
  1132.        Input:    The vdi_handle parameter is a handle to a VDI virtual screen
  1133.                  workstation.
  1134.  
  1135.        Returns:  Nothing.
  1136.  
  1137.        See Also: apl_vopen() apl_cleanup()
  1138.  
  1139.        Details:  This function closes a VDI workstation that was opened with
  1140.                  a call to apl_vopen().  It will not close the shared
  1141.                  workstation; only apl_cleanup() can close the shared
  1142.                  workstation.
  1143.  
  1144.        Source:   aesfuncs\aplvwork.c
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.        
  1183.        ======================================================================
  1184.        GemFast v1.8                                                   Page 13
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.        short apl_vopen(void)
  1194.        ______________________________________________________________________
  1195.  
  1196.        Summary:  Open a VDI virtual screen workstation.
  1197.  
  1198.        Input:    Nothing.
  1199.  
  1200.        Returns:  A VDI handle, or 0 if no handles are available.
  1201.  
  1202.        See Also: apl_vclose() 
  1203.  
  1204.        Details:  This function provides a simple way to open a VDI screen
  1205.                  workstation.  It automatically handles the work_in and
  1206.                  work_out arrays, and other basic details for you.  
  1207.  
  1208.                  The values from the work_out array are available in the
  1209.                  global array gl_vwout any time after a VDI workstation
  1210.                  (including the shared workstation) is opened.  The values
  1211.                  returned by vq_extnd(,1) are also available in gl_vxout.
  1212.  
  1213.                  The work_in array is built automatically to set up the
  1214.                  following default configuration:
  1215.  
  1216.                      static short work_in[11] = {
  1217.                          -1, /* device driver (filled in at runtime) */
  1218.                           1, /* polyline type    (normal)            */
  1219.                           1, /* polyline color   (black)             */
  1220.                           1, /* polymarker type  (dot)               */
  1221.                           1, /* polymarker color (black)             */
  1222.                           1, /* text face        (standard)          */
  1223.                           1, /* text color       (black)             */
  1224.                           1, /* fill interior    (solid)             */
  1225.                           8, /* fill style       (solid)             */
  1226.                           1, /* fill color       (black)             */
  1227.                           2  /* use RC coordinate system             */
  1228.                      }; 
  1229.  
  1230.                  After the workstation is open, you can change its attributes
  1231.                  as you wish, using the vs_whatever() VDI functions.
  1232.  
  1233.        Source:   aesfuncs\aplvwork.c
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.        
  1249.        ======================================================================
  1250.        GemFast v1.8                                                   Page 14
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.        short apl_vshared(void)
  1260.        ______________________________________________________________________
  1261.  
  1262.        Summary:  Returns the handle for the shared VDI workstation, opening
  1263.                  the shared workstation if necessary.
  1264.  
  1265.        Input:    Nothing.
  1266.  
  1267.        Returns:  The handle of the shared VDI virtual screen workstation, or
  1268.                  0 if no workstation is available.
  1269.  
  1270.        See Also: apl_vopen() apl_cleanup()
  1271.  
  1272.        Details:  This function opens the shared VDI workstation if it isn't
  1273.                  open already, and returns the handle for it.
  1274.  
  1275.                  GemFast library routines need a lot VDI-based services,
  1276.                  especially for blitting and custom object drawing.  Instead
  1277.                  of having each routine open and close VDI workstations as
  1278.                  needed, all routines now use the shared workstation.  Once
  1279.                  the shared workstation is opened, it remains open from that
  1280.                  point on.  (Unless you call apl_cleanup() to close it.)  If
  1281.                  opened during the run of a program, appl_exit() closes it.
  1282.  
  1283.                  Your application can use the shared workstation for
  1284.                  blitting, but I strongly recommend against using it for
  1285.                  other VDI operations.  Any given library function could want
  1286.                  the shared workstation, and it expects the attributes to be
  1287.                  set to a standard configuration.  It would be difficult for
  1288.                  you determine whether it's "safe" to change the attributes
  1289.                  at any given point to do some sort of output and then set
  1290.                  them back.  The shared workstation can even get used by the
  1291.                  AES itself, because some library routines install custom
  1292.                  G_USERDEF drawing routines that get called by the AES
  1293.                  automatically.
  1294.  
  1295.        Source:   aesfuncs\aplvwork.c
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.        
  1315.        ======================================================================
  1316.        GemFast v1.8                                                   Page 15
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.        void apl_xexit(void)
  1326.        void appl_exit(void)
  1327.        ______________________________________________________________________
  1328.  
  1329.        Summary:  Cleanup acquired system resources, inform the AES that the
  1330.                  program is about to exit.
  1331.  
  1332.        NOTE:     A macro in GEMFAST.H remaps appl_exit to apl_xexit, so that
  1333.                  the extended exit function is automatically used when you
  1334.                  recompile your existing code.
  1335.  
  1336.        Input:    Nothing.
  1337.  
  1338.        Returns:  Nothing.
  1339.  
  1340.        See Also: apl_xinit() apl_cleanup()
  1341.  
  1342.        Details:  Currently, apl_xexit() just calls apl_cleanup() to release
  1343.                  permanent and transient resources, then it calls the real
  1344.                  appl_exit() function for you.  The primary purpose for the
  1345.                  extended exit function right now is to ensure that the
  1346.                  shared VDI workstation gets closed.  In the future, it'll do
  1347.                  more.
  1348.  
  1349.        Source:   aesfuncs\aplxinit.c
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.        
  1381.        ======================================================================
  1382.        GemFast v1.8                                                   Page 16
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.        short apl_xinit(void)
  1392.        short appl_init(void)
  1393.        ______________________________________________________________________
  1394.  
  1395.        Summary:  Register your application with the AES, and load values into
  1396.                  the GemFast-defined global variables.
  1397.  
  1398.        NOTE:     A macro in GEMFAST.H remaps appl_exit to apl_xexit, so that
  1399.                  the extended init function is automatically used when you
  1400.                  recompile your existing code.
  1401.  
  1402.        Input:    Nothing.
  1403.  
  1404.        Returns:  Application ID return by the AES, or a negative number if
  1405.                  the AES is not available.
  1406.  
  1407.        See Also: apl_xexit() 
  1408.  
  1409.        Details:  The extended init first calls the real appl_init() function. 
  1410.                  If that succeeds, it calls several inquiry functions to load
  1411.                  the global variables with data that most GEM programs need,
  1412.                  such as the sizes of the system desktop.  The chapter Global
  1413.                  Variables contains complete details on the global variables
  1414.                  initialized by this function.
  1415.  
  1416.        Source:   aesfuncs\aplxinit.c
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.        
  1447.        ======================================================================
  1448.        GemFast v1.8                                                   Page 17
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.        Error Message Library
  1458.  
  1459.  
  1460.                  The error message library contains several functions which
  1461.                  help support error reporting functions in the forms library. 
  1462.                  They are not, strictly speaking, GEM functions.  You may
  1463.                  find them useful even in your non-GEM programs.
  1464.  
  1465.                  The functions allow you to specify tables of error messages
  1466.                  and their associated error codes.  You can then report an
  1467.                  error message just by passing the code to frm_[q]error().
  1468.  
  1469.                  TOS reserves error codes in the range of -1 to -128.  Code 0
  1470.                  is, by convention, success.  Many compilers reserve a range
  1471.                  of codes for runtime library errors (HSC reserves -129
  1472.                  through -255 for this); consult your compiler documentation
  1473.                  for details.  Some compilers reserve a range of positive
  1474.                  rather than negative numbers.
  1475.  
  1476.                  GemFast reserves codes in the range of -15100 through -15199
  1477.                  for reporting GemFast internal errors.  This seems like a
  1478.                  small range in the middle of nowhere, and shouldn't conflict
  1479.                  with existing code.
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.        
  1513.        ======================================================================
  1514.        GemFast v1.8                                                   Page 18
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.        char * exterror(short errcode)
  1524.        ______________________________________________________________________
  1525.  
  1526.        Summary:  Return a text description of the specified error code.
  1527.  
  1528.        Input:    The errcode parameter is the numeric error code you want the
  1529.                  text description of.
  1530.  
  1531.        Returns:  A pointer to a \0-terminated string describing the error. 
  1532.                  Do not modify the string this points to.  The return value
  1533.                  is guaranteed to be non-NULL, but it may point to an empty
  1534.                  string ("").
  1535.  
  1536.        NOTE:     You must code a #include "exterror.h" to use this function.
  1537.  
  1538.        See Also: exterrset() 
  1539.                  strerror()  (in your compiler's library)
  1540.  
  1541.        Details:  This function is similar to the strerror() function defined
  1542.                  by ANSI, except that it first searches tables of
  1543.                  application-specific error messages (installed by the
  1544.                  application using exterrset()).  If the application-specific
  1545.                  tables don't contain a message for the specified error
  1546.                  number, this function calls the standard strerror() function
  1547.                  to obtain the system-defined message.
  1548.  
  1549.                  This function can also deal with positive error codes, both
  1550.                  in the extended message tables and for strerror() if your
  1551.                  compiler's errno system uses positive error codes.
  1552.  
  1553.        Source:   aesfuncs\exterror.c
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.        
  1579.        ======================================================================
  1580.        GemFast v1.8                                                   Page 19
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.        short exterrset(_Err_tab *ptab, short install_or_remove)
  1590.        ______________________________________________________________________
  1591.  
  1592.        Summary:  Installs or removes a table of application-specific error
  1593.                  codes and their associated messages.
  1594.  
  1595.        Input:    The ptab parameter is a pointer to an array of _Err_tab
  1596.                  structures coded in your application.  
  1597.  
  1598.                  The install_or_remove parameter is a flag indicating whether
  1599.                  the specified table is to be installed in the list of
  1600.                  extended message tables, or removed from that list.  A table
  1601.                  can be safely removed more than once.
  1602.  
  1603.        Returns:  0 on success, or -1 if there are no more slots available in
  1604.                  the extended tables list.
  1605.  
  1606.        NOTE:     You must code a #include "exterror.h" to use this function.
  1607.  
  1608.        See Also: exterror()
  1609.  
  1610.        Details:  This function installs or removes tables of application-
  1611.                  specific error messages.  The exterror() function returns
  1612.                  message from these tables.  You create extended message
  1613.                  tables by coding an array of _Err_tab structures and
  1614.                  initializing the array with your codes and messages.  The
  1615.                  _Err_tab structure is defined in EXTERROR.H, as follows:
  1616.  
  1617.                      typedef struct _Err_tab {
  1618.                          int   code;
  1619.                          char *msg;
  1620.                      } _Err_tab;
  1621.  
  1622.                  To create a table of extended messages, code an array and
  1623.                  initialize it with your errcode/msg pairs.  Use an error
  1624.                  code value of zero to indicate the end of the table.  You
  1625.                  can define any error code in the range of -32768 through
  1626.                  32767, excluding code 0.  If you provide messages for
  1627.                  system-defined error codes, exterror() finds your messages
  1628.                  first, and returns them instead of calling strerror().  In
  1629.                  other words, you can override the wording of system
  1630.                  messages.
  1631.  
  1632.        Example:  The following is an example of creating and installing an
  1633.                  extended error message table defining 3 application-specific
  1634.                  messages: 
  1635.  
  1636.                      static _Err_tab my_messages[] = {
  1637.                          {-300, "Input must be between 0 and 200"},
  1638.                          {-301, "Cannot locate configuration file"},
  1639.                          {-302, "Internal data corrupted"},
  1640.                          {0,    NULL};
  1641.  
  1642.                      exterrset(my_messages, TRUE);
  1643.  
  1644.        
  1645.        ======================================================================
  1646.        GemFast v1.8                                                   Page 20
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.                  Note that I don't check the return code from exterrset() in
  1656.                  the example.  You really should check it. ::grin::
  1657.  
  1658.                  The internal list is currently configured for up to 8
  1659.                  extended message tables.
  1660.  
  1661.        Source:   aesfuncs\exterror.c
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.        
  1711.        ======================================================================
  1712.        GemFast v1.8                                                   Page 21
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.        Forms and Dialogs Library
  1722.  
  1723.  
  1724.                  The forms and dialogs library contains functions related to
  1725.                  dialog processing.  Some of the functions are designed to
  1726.                  help you conduct your own dialogs, and others invoke pre-
  1727.                  written dialogs using your parameters and messages.  
  1728.  
  1729.                  The pre-written dialogs use options and strings you specify,
  1730.                  and dynamically build and conduct a dialog based on them. 
  1731.                  For this reason, they are collectively referred to as the
  1732.                  'dynamic' dialogs.  The dynamic dialogs are divided into two
  1733.                  groups, the basic functions and the quick functions.  The
  1734.                  basic functions allow you to specify options and a variety
  1735.                  of exit buttons.  The quick functions are easy to call; they
  1736.                  provide default options and buttons.  (The quick functions
  1737.                  do not execute faster; they're quicker to code.)  The basic
  1738.                  dynamic dialogs exist primarily to support the higher-level
  1739.                  quick dialogs, but there's no reason you can't use them
  1740.                  directly if you need the extra options or buttons.
  1741.  
  1742.  
  1743.             Summary of Dialog Functions
  1744.  
  1745.  
  1746.                  The functions which help you conduct your own dialogs are:
  1747.  
  1748.                      frm_confine     Confines dialog to rectangular area.
  1749.                      frm_defaults    Sets default options.
  1750.                      frm_dialog      Conducts your standard dialog.
  1751.                      frm_menu        Conducts your menu (object tree) dialog.
  1752.                      frm_enableblit  Enables screen save/restore via blit.
  1753.                      frm_eflag       Reports error made by user in a dialog.
  1754.                      frm_mkmoveable  Makes your dialog moveable.
  1755.                      frm_desktop     Installs your custom desktop.
  1756.                      frm_sizes       Calculates dialog's on-screen sizes.
  1757.  
  1758.                  The basic dynamic dialogs are:
  1759.  
  1760.                      frm_dsdialog    Automatic text dialog - hard to use.
  1761.                      frm_nldialog    Automatic text dialog - easier to use.
  1762.                      frm_dsmenu      Automatic menu dialog - hard to use.
  1763.                      frm_nlmenu      Automatic menu dialog - easier to use.
  1764.                      frm_printf      Formatted text dialog, like printf().
  1765.                      frm_progress    Formatted progress display.
  1766.                      frm_error       Formatted error reporting.
  1767.                      frm_verror      Alternate form of frm_error.
  1768.                      frm_vprintf     Alternate form of frm_printf.
  1769.                      frm_vprogress   Alternate form of frm_progress.
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.        
  1777.        ======================================================================
  1778.        GemFast v1.8                                                   Page 22
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.                  The quick dynamic dialogs are:
  1788.  
  1789.                      frm_qchoice     Formatted text and choice of 5 buttons.
  1790.                      frm_qerror      Formatted error msg - 'Continue' button.
  1791.                      frm_qfatal      Formatted error msg - 'Fatal' button.
  1792.                      frm_qmenu       Automatic menu (like dropdown in a box).
  1793.                      frm_qtext       Formatted text display.
  1794.                      frm_question    Formatted yes/no question.
  1795.  
  1796.                  If you look in the GemFast source code, you may find some
  1797.                  other functions in the frm_ family.  Do NOT use any
  1798.                  functions not described in this document.  If it's not
  1799.                  documented here, I guarantee you the calling standard for it
  1800.                  will change in the next version, and your programs will
  1801.                  break.  If it wasn't in a state of flux, it'd be documented.
  1802.  
  1803.  
  1804.             Dialog Processing Options
  1805.  
  1806.  
  1807.                  At the root of all dialog processing in GemFast is the
  1808.                  frm_dialog() function.  All dynamic dialogs eventually end
  1809.                  up in it, including the menu dialogs.  You can also use it
  1810.                  for processing your custom application dialogs.  There are a
  1811.                  variety of options that frm_dialog() can act on for you. 
  1812.                  Several of the dynamic dialogs have options that apply
  1813.                  specifically to them, but not to dialog processing in
  1814.                  general.  All dialog processing options are listed below.  
  1815.  
  1816.                  In addition to options which control the appearance of a
  1817.                  dialog, some functions accept action flags which dictate the
  1818.                  steps or parts of a dialog to be performed.  This applies
  1819.                  primarily to the frm_dialog() function.  Because they are
  1820.                  specific to only a few of the functions, action flags are
  1821.                  described along with the function that uses them.
  1822.  
  1823.                  It makes sense for all dialogs in an application to behave
  1824.                  pretty much the same way, so GemFast provides the
  1825.                  frm_defaults() function to specify default dialog options. 
  1826.                  You can set the default options once, during program
  1827.                  startup, then use just FRM_NORMAL in all your dialog
  1828.                  function calls, and everything (including dynamic dialogs
  1829.                  which don't let you specify any options) will behave
  1830.                  according to the defaults you set.
  1831.  
  1832.                  The options parameter for all dialog library functions is a
  1833.                  longword.  It is important for you to use the constant
  1834.                  FRM_NORMAL instead of just 0 or NORMAL when you want no
  1835.                  special options.  Options are encoded in the longword as a
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.        
  1843.        ======================================================================
  1844.        GemFast v1.8                                                   Page 23
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.                  collection of bits.  The bits for different types of options
  1854.                  appear in distinct places in the longword (not that this
  1855.                  really has much affect on you in the current version) as
  1856.                  follows:
  1857.  
  1858.                      0xAUDDBBBB
  1859.                        ||| |______ Basic options for all dialog handling.
  1860.                        |||________ Dynamic dialog options.
  1861.                        ||_________ User options; never touched by GemFast.
  1862.                        |__________ Actions.
  1863.  
  1864.  
  1865.             Basic Dialog Options
  1866.  
  1867.  
  1868.                  The FRM_NORMAL option is really a placeholder that says you
  1869.                  want no options other than the defaults already established.
  1870.  
  1871.                  The FRM_EXPLODE option draws exploding-box graphics during
  1872.                  the start and finish phases of a dialog.  The small box for
  1873.                  the grow/shrink calls is one-fifth the size of the full
  1874.                  dialog, centered under the full dialog.
  1875.  
  1876.                  The FRM_MOUSEARROW option forces the mouse cursor shape to
  1877.                  an arrow for the duration of the dialog, then changes it
  1878.                  back to the prior shape when the user exits.
  1879.  
  1880.                  The FRM_CENTER option centers the dialog within the desktop
  1881.                  before drawing it.
  1882.  
  1883.                  The FRM_NEARMOUSE option centers the dialog over the current
  1884.                  mouse location (adjusting as necessary to keep the dialog
  1885.                  wholly on-screen) before drawing it.  FRM_NEARMOUSE takes
  1886.                  precedence over FRM_CENTER when both are specified.
  1887.  
  1888.                  The FRM_USEBLIT option saves and restores the screen under
  1889.                  the dialog using blits instead of redraw messages.  You must
  1890.                  call frm_enableblit() at least once before this option is
  1891.                  honored.  This option only has effect when the frm_dialog()
  1892.                  action flags are equal to FRM_DCOMPLETE (ie, when you're
  1893.                  doing all phases of the dialog in a single call).  The blit
  1894.                  buffer is allocated and freed by frm_dialog().  If the
  1895.                  allocation fails, the FRM_USEBLIT option is turned off for
  1896.                  the duration of that frm_dialog() call.
  1897.  
  1898.                  The FRM_MOVEABLE option designates the dialog as moveable
  1899.                  even if no object in the dialog has the FRM_MOVER bit on in
  1900.                  its ob_flags.  The FRM_USEBLIT option has to be in effect
  1901.                  for this option to function, and all conditions required for
  1902.                  FRM_USEBLIT to take effect apply to this option as well.  If
  1903.                  you have used frm_mkmoveable() to designate a specific mover
  1904.                  object within a dialog, this option has no effect; the mover
  1905.                  object will always move the dialog regardless of this
  1906.                  option.  If you specify this option for a dialog that has no
  1907.  
  1908.        
  1909.        ======================================================================
  1910.        GemFast v1.8                                                   Page 24
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.                  designated mover object, the root object becomes the dialog
  1920.                  mover automatically.  The basic point to this option is that
  1921.                  you can set it as the default, and all your dialogs suddenly
  1922.                  become moveable even when you haven't designed in a mover
  1923.                  object.  If allocation of a blit buffer fails, the dialog is
  1924.                  treated as unmovable.  When your dialogs stop moving, you're
  1925.                  getting low on memory.
  1926.  
  1927.                  The FRM_NODEFAULTS option can be passed to frm_dialog() or
  1928.                  the dynamic dialogs to disable the default options for that
  1929.                  specific call. When you pass FRM_NODEFAULTS as one of your
  1930.                  options, the default options are ignored, and only the
  1931.                  options passed along with FRM_NODEFAULTS are used.
  1932.  
  1933.  
  1934.             Dynamic Dialog Options
  1935.  
  1936.  
  1937.                  The FRM_DSHADOWED option draws the parent box of the dynamic
  1938.                  dialog (text or menu) as a SHADOWED object instead of an
  1939.                  OUTLINED object.  
  1940.  
  1941.                  The FRM_DMUSTSELECT option is interpreted based on the type
  1942.                  of dialog.  For a text dialog, it indicates that there is no
  1943.                  default exit button; the user "must select" a button with
  1944.                  the mouse.  For a menu dialog, it indicates that the user
  1945.                  must click on a selectable item; clicking outside the dialog
  1946.                  box does not end the dialog and return NO_OBJECT. 
  1947.  
  1948.                  The FRM_DEFAULTLEFT option causes the default button in
  1949.                  dynamic dialogs to be the leftmost (rather than rightmost)
  1950.                  button.  For the frm_question() dialog, it also causes the
  1951.                  left button to be 'Yes' and the right button to be 'No'.  
  1952.  
  1953.                  The FRM_MEXITPARENT option causes the menu dialog to return
  1954.                  NO_OBJECT as soon as the mouse leaves the dialog box.  This
  1955.                  option applies only to menu dialogs and has no effect on
  1956.                  text dialogs.
  1957.  
  1958.                  The FRM_MEXITVICINITY option cause the menu dialog to return
  1959.                  NO_OBJECT as soon as the mouse leaves the near vicinity of
  1960.                  the dialog box.  The vicinity is an area that extends four
  1961.                  character widths to either side of the dialog box and two
  1962.                  characters heights above and below it.  This option applies
  1963.                  only to menu dialogs and has no effect on text dialogs.
  1964.  
  1965.                  The MUSTSELECT option takes precedence over MEXITPARENT and
  1966.                  MEXITVICINITY.  When MUSTSELECT is specified, you are
  1967.                  guaranteed never to get a NO_OBJECT return value.
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.        
  1975.        ======================================================================
  1976.        GemFast v1.8                                                   Page 25
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.             Dynamic Dialog Defaults
  1986.  
  1987.  
  1988.                  For dynamic dialogs that allow you to specify a list of exit
  1989.                  buttons, a NULL button pointer gives you a single exit
  1990.                  button containing "Continue" as its text.  You also get a
  1991.                  Continue button for the quick dynamic dialogs that don't let
  1992.                  you specify a list of buttons.
  1993.  
  1994.                  While it's pretty pointless to do so, if you pass a NULL
  1995.                  pointer for the text string or format string describing the
  1996.                  body of the dialog, the body will be a single line
  1997.                  containing "<no message>".
  1998.  
  1999.                  All dynamic dialogs use a default internal options list. 
  2000.                  These automatic defaults are added to the options you set
  2001.                  with frm_defaults() and whatever you specify in the call. 
  2002.                  The automatic dynamic dialog defaults are:
  2003.  
  2004.                    (FRM_CENTER | FRM_USEBLIT | FRM_MOVEABLE | FRM_MOUSEARROW)
  2005.  
  2006.                  As usual, if you specify NEARMOUSE it takes precedence over
  2007.                  the default CENTER.  The USEBLIT and MOVEABLE defaults are
  2008.                  honored only if you've called frm_enableblit().  If you pass
  2009.                  FRM_NODEFAULTS to a dynamic dialog, the defaults listed
  2010.                  above are not used, only the options you specify in that
  2011.                  call are used.  An oddball exception is that if you specify
  2012.                  NODEFAULTS and don't include CENTER or NEARMOUSE, CENTER is
  2013.                  assumed (otherwise where would the dialog be placed?).
  2014.  
  2015.  
  2016.             Text and Button Formatting in Dynamic Dialogs
  2017.  
  2018.  
  2019.                  A number of common factors apply to all dynamic dialog
  2020.                  functions that handle formatted text and/or multiple
  2021.                  buttons.  These details apply to any function which lists
  2022.                  frm_printf() in its See Also: section.
  2023.  
  2024.                  Dynamic dialogs construct a dialog box around your text
  2025.                  and/or button.  The dialog box is automatically sized to
  2026.                  contain the widest line of text in the body, or wide enough
  2027.                  to hold all the buttons, whichever is greater.  It is YOUR
  2028.                  responsibility to ensure that the strings don't result in a
  2029.                  width greater than the current screen width.
  2030.  
  2031.                  Dynamic text dialogs can display up to 20 lines of formatted
  2032.                  text, with a total of no more than 2k for the entire
  2033.                  message.  The 2k limit is more than enough to format 20
  2034.                  lines of 80 characters, and should thus not be a problem. 
  2035.                  The GEMFAST.H file defines a constant, FRM_DSMAXLINES if you
  2036.                  should need to refer to the line limit in your code.
  2037.  
  2038.                  Any line of text in the message which has a 0x7F character
  2039.  
  2040.        
  2041.        ======================================================================
  2042.        GemFast v1.8                                                   Page 26
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.                  in the first position is automatically centered horizontally
  2052.                  (the 0x7F is not displayed).  A 0x7F character in any other
  2053.                  position displays as normal (a little triangle thingy on my
  2054.                  system).
  2055.  
  2056.                  Dynamic dialogs which allow you to specify multiple buttons
  2057.                  can display a maximum of 5 buttons.  The lengths of all the
  2058.                  button text strings should not exceed about 70 characters,
  2059.                  or the dialog will end up being wider than the typical 80-
  2060.                  character screen width.  All buttons are formatted to the
  2061.                  same width, that required to hold the longest button string. 
  2062.                  The buttons are distributed uniformly across the bottom of
  2063.                  the dialog box.  The GEMFAST.H file defines a constant,
  2064.                  FRM_DSMAXBUTTONS if you should need to refer to the button
  2065.                  limit in your code..
  2066.  
  2067.                  The button selected by the user is the return value from the
  2068.                  dynamic dialog function.  The leftmost button is 0, and the
  2069.                  number increments as you proceed right.
  2070.  
  2071.                  If any button has a 0x7F character in the first character,
  2072.                  that button is made the default exit button, regardless of
  2073.                  the FRM_DMUSTSELECT or FRM_DEFAULTLEFT options.  (Don't put
  2074.                  a 0x7F on more than one button!)  If no buttons are
  2075.                  explicitly marked as the default with 0x7F, the following
  2076.                  rules apply.
  2077.  
  2078.                  If FRM_DEFAULTLEFT is in effect, the leftmost button is the
  2079.                  default exit button.  This conforms to the new Atari
  2080.                  application guidelines released with the Falcon 030
  2081.                  documentation.  An increasing number of applications are
  2082.                  going to be using the leftmost button as the default, and
  2083.                  that button will generally be the 'Yes', 'Okay', 'Continue',
  2084.                  or other positive-action selection.  The rightmost button
  2085.                  should be Exit, Cancel, No, or the negative-action button.  
  2086.  
  2087.                  If FRM_DMUSTSELECT is in effect, none of the buttons are
  2088.                  automatically marked as the default exit button.
  2089.  
  2090.                  Otherwise, the rightmost button is the default exit button. 
  2091.                  This is a holdover from long ago, maintained for
  2092.                  compatibility; it does not conform to Atari's current
  2093.                  guidelines.  You should set FRM_DEFAULTLEFT in your
  2094.                  frm_defaults() list, and make any necessary changes to your
  2095.                  existing dynamic dialog calls, as soon as possible.
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.        
  2107.        ======================================================================
  2108.        GemFast v1.8                                                   Page 27
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.        void frm_confine(OBJECT *ptree, GRECT *boundrect)
  2118.        ______________________________________________________________________
  2119.  
  2120.        Summary:  Adjust the location of an object tree so that it is confined
  2121.                  within a specified area.
  2122.  
  2123.        Input:    The ptree parameter is a pointer to the tree to adjust.
  2124.  
  2125.                  The boundrect parameter is a pointer to the rectangle in
  2126.                  which the tree is to be placed.
  2127.  
  2128.        Returns:  Nothing.
  2129.  
  2130.        See also: rc_confine()
  2131.  
  2132.        Details:  This function adjusts the x/y values of the object tree as
  2133.                  needed to keep that tree within the specified rectangle.  It
  2134.                  never modifies the width or height of the tree; if the tree
  2135.                  will not wholly fit within the boundary rectangle, it is
  2136.                  aligned to the upper and left sides of the boundary as
  2137.                  needed.  This function takes OUTLINED and SHADOWED flags
  2138.                  into account, and makes sure the dialog is entirely within
  2139.                  the boundary, visually.
  2140.  
  2141.        Source:   aesfuncs\frmconfi.c
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.        
  2173.        ======================================================================
  2174.        GemFast v1.8                                                   Page 28
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.        long frm_defaults(long options)
  2184.        ______________________________________________________________________
  2185.  
  2186.        Summary:  Get or set default dialog processing options.
  2187.  
  2188.        Input:    The options parameter specifies the new default options as a
  2189.                  bitmap; the available values are described under Dialog
  2190.                  Processing Options.  In addition, the following special
  2191.                  value may be passed instead of the standard options:
  2192.  
  2193.                    FRM_GETDEFAULTS - Return the current defaults without
  2194.                                      changing them.
  2195.  
  2196.        Returns:  The default options in effect before the call.
  2197.  
  2198.        See Also: frm_dialog()
  2199.  
  2200.        Details:  The dialog functions support a variety of processing
  2201.                  options.  You can pass options to most of them on each call. 
  2202.                  In addition, you can use this function to set default
  2203.                  options that will be used on every subsequent call to
  2204.                  frm_dialog() or a dynamic dialog.  The default options set
  2205.                  by this function will apply to any other library function
  2206.                  which lists frm_defaults() in its "See Also" section.
  2207.  
  2208.                  Library routines will NOT change the default options behind
  2209.                  your back.  Library routines calling frm_dialog() do NOT use
  2210.                  FRM_NODEFAULTS to override your preferences.
  2211.  
  2212.        Source:   aesfuncs\frmdialo.c
  2213.  
  2214.  
  2215.  
  2216.  
  2217.  
  2218.  
  2219.  
  2220.  
  2221.  
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.        
  2239.        ======================================================================
  2240.        GemFast v1.8                                                   Page 29
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.        void frm_desktop(long options, OBJECT *ptree)
  2250.        ______________________________________________________________________
  2251.  
  2252.        Summary:  Installs or removes an object tree as the system desktop.
  2253.  
  2254.        Input:    The options parameter specifies the installation option, use
  2255.                  one of the following values:
  2256.  
  2257.                    FRM_NORMAL   -    No options; the tree is installed
  2258.                                      without any changes.
  2259.                    FRM_CENTER   -    The tree is automatically fitted to the
  2260.                                      desktop.  
  2261.  
  2262.                  The ptree parameter is a pointer to the object tree to
  2263.                  install as the new desktop.  When NULL, it indicates you are
  2264.                  removing any custom desktop you've previously installed.
  2265.  
  2266.        Returns:  Nothing.
  2267.  
  2268.        See Also:
  2269.  
  2270.        Details:  This function makes the specified object tree the new
  2271.                  desktop, for the duration of your program or until you
  2272.                  remove it with another call to this function.  Desk
  2273.                  accessories MUST NOT use this function.
  2274.  
  2275.                  The desktop is automatically repainted by the AES; it acts
  2276.                  as if the AES is running an evnt_multi() loop internally,
  2277.                  and responds to redraw messages for the desktop by calling
  2278.                  objc_draw() on the desktop tree.  The default system desktop
  2279.                  is a single G_BOX object with no borders or outline.
  2280.  
  2281.                  By installing your own dialog as the system desktop, you can
  2282.                  get the benefits of a windowed program without the hassle of
  2283.                  using window redraw logic in your program.  If your
  2284.                  application has a single main dialog box, you can install it
  2285.                  as the desktop and call other dialog functions -- even the
  2286.                  file selector -- and your main dialog is automatically
  2287.                  redrawn as other windows and dialogs are closed or moved.
  2288.  
  2289.                  After installing your tree as the desktop, this function
  2290.                  sends out redraw messages which cause it to be painted
  2291.                  automatically.  You never need to call objc_draw() to show
  2292.                  the tree.  If the tree is a dialog, just call form_do() (or
  2293.                  frm_dialog(FRM_DDO)) to start the dialog, and don't call
  2294.                  form_dial(FMD_FINISH) when you're done.
  2295.  
  2296.                  To use a dialog as the desktop, I recommend that you create
  2297.                  the main dialog box as a borderless non-outlined box filled
  2298.                  with solid green.   Make the second object in the tree a box
  2299.                  with an inside width of 2 and OUTLINED.  (IE, the second
  2300.                  object is a box just like the one used as the first object
  2301.                  in a normal dialog.)  Then call this function, passing an
  2302.                  option of FRM_CENTER.  The FRM_CENTER option causes this
  2303.  
  2304.        
  2305.        ======================================================================
  2306.        GemFast v1.8                                                   Page 30
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.                  function to automatically adjust the main box (the first
  2316.                  object) to be exactly the size of the system desktop, and
  2317.                  then it centers the second object (the actual dialog box)
  2318.                  within the desktop.  Visually, you get the effect of a
  2319.                  dialog that has been form_center'd on a regular desktop.
  2320.  
  2321.                  If you don't use the FRM_CENTER option, you MUST ensure that
  2322.                  the first object in the tree is exactly the size of the
  2323.                  desktop.
  2324.  
  2325.                  When your desktop root object has been defined as a box
  2326.                  filled with a solid non-background color (eg, a standard
  2327.                  solid green desktop), this routine modifies the box to a 50%
  2328.                  gray fill when running on a monochrome system.  (Otherwise
  2329.                  the "solid green" box would appear as solid black on a
  2330.                  monochrome monitor.)  In other words, if you follow the
  2331.                  recommendation of designing a solid green desktop, this
  2332.                  routine automatically adjusts the desktop to match the
  2333.                  standard system desktop when running on monochrome monitors.
  2334.  
  2335.        Source:   aesfuncs\frmdeskt.c
  2336.  
  2337.  
  2338.  
  2339.  
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.        
  2371.        ======================================================================
  2372.        GemFast v1.8                                                   Page 31
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.        short frm_dialog(long options, OBJECT *ptree, short startobj)
  2382.        ______________________________________________________________________
  2383.  
  2384.        Summary:  Conducts all or part of a dialog with the user.
  2385.  
  2386.        Input:    The options parameter specifies actions and options as a
  2387.                  bitmap; the available values are described under Dialog
  2388.                  Processing Options.  In addition to the options, any of the
  2389.                  following actions can be ORed into the parameter value:
  2390.  
  2391.                    FRM_DSTART     -  Do the FMD_START and FMD_GROW.
  2392.                    FRM_DDRAW      -  Do the objc_draw().
  2393.                    FRM_DDO        -  Do the form_do().
  2394.                    FRM_DFINISH    -  Do the FMD_SHRINK and FMD_FINISH.
  2395.                    FRM_DCOMPLETE  -  Do all of the above in one call.
  2396.  
  2397.                  If no actions are provided, FRM_DCOMPLETE is assumed.
  2398.  
  2399.                  The ptree parameter is a pointer to the dialog tree.
  2400.  
  2401.                  The startobj parameter is interpreted according the action
  2402.                  options.  If just FRM_DDRAW is requested, startobj is the
  2403.                  object to start drawing at.  If actions other than drawing
  2404.                  are also requested, the full object tree is drawn, and
  2405.                  startobj is the initial text edit object for form_do().
  2406.  
  2407.        Returns:  The index of the exit object.  Be aware that if the exit
  2408.                  object was a TOUCHEXIT, and the user double-clicked on it,
  2409.                  the high bit in the return value is set (making it look
  2410.                  negative).  If the exit object had the EXIT or DEFAULT bits
  2411.                  on in its ob_flags, it is automatically set to ~SELECTED,
  2412.                  both in the object structure, and visually on the screen.
  2413.  
  2414.        See Also: frm_enableblit() frm_defaults()
  2415.  
  2416.        Details:  The most frequent use of this function is really fairly
  2417.                  simple.  To conduct a complete interaction with a user, you
  2418.                  only need to code something like:
  2419.  
  2420.                     selection = frm_dialog(FRM_CENTER, mydialog, 0);
  2421.  
  2422.                  You can, of course, use any of the other options.  You can
  2423.                  also use this function to conduct a dialog "in pieces".  (A
  2424.                  disadvantage to this is that a dialog conducted in pieces
  2425.                  won't honor the USEBLIT and MOVEABLE options.)  Such a
  2426.                  sequence usually appears something like:
  2427.  
  2428.                    - Start dialog using frm_dialog(FRM_DSTART|FRM_DDRAW).
  2429.                    - Loop:
  2430.                    -     Conduct interaction using frm_dialog(FRM_DDO).
  2431.                    -     Validate user's actions, if any errors are found,
  2432.                          use frm_eflag() to report them.
  2433.                    -     When the validations are good, exit the loop.
  2434.                    - Close dialog using frm_dialog(FRM_DFINISH).
  2435.  
  2436.        
  2437.        ======================================================================
  2438.        GemFast v1.8                                                   Page 32
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.                  When you're processing a dialog in pieces, it can be
  2448.                  important to know which options are processed during which
  2449.                  pieces of the dialog.  Processing occurs in several phases:
  2450.  
  2451.                    setup       - 1.  Call wnd_update(BEG_UPDATE).  
  2452.                                  2.  If FRM_USEBLIT is set, ensure that
  2453.                                      frm_enableblit() has been called and
  2454.                                      that FRM_DCOMPLETE was specified. 
  2455.                                      Ensure that a blit buffer is available. 
  2456.                                      If any of those are false, turn off
  2457.                                      FRM_USEBLIT.  
  2458.                                  3.  If the dialog contains an object flagged
  2459.                                      as the FRM_MOVER object, set
  2460.                                      FRM_MOVEABLE on.  
  2461.                                  4.  If FRM_MOVEABLE has been set, ensure
  2462.                                      that FRM_USEBLIT is in effect.  If there
  2463.                                      isn't an FRM_MOVER object, make the root
  2464.                                      object the mover.
  2465.  
  2466.                    FRM_DSTART  - 1.  Center the dialog on the desktop if
  2467.                                      FRM_CENTER is set, or center it over the
  2468.                                      mouse if FRM_NEARMOUSE is set.
  2469.                                  2.  Save the screen to the blit buffer if
  2470.                                      FRM_USEBLIT is set. Do the FMD_START,
  2471.                                      and if FRM_EXPLODE is set do the
  2472.                                      FMD_GROW.
  2473.  
  2474.                    FRM_DDRAW   -     Do the objc_draw().
  2475.  
  2476.                    FRM_DDO     - 1.  Change the mouse to an arrow if
  2477.                                      FRM_MOUSEARROW is set.  
  2478.                                  2.  Do the form_do().  If the exit object
  2479.                                      was the FRM_MOVER object, handle the
  2480.                                      dialog move, then loop back into
  2481.                                      form_do() again.
  2482.                                  3.  Reset the ob_state of the exit object to
  2483.                                      ~SELECTED, if it's an EXIT or DEFAULT
  2484.                                      object. 
  2485.                                  4.  Restore the mouse shape.
  2486.  
  2487.                    FRM_DFINISH - 1.  Do the FMD_SHRINK if FRM_EXPLODE is set. 
  2488.  
  2489.                                  2.  If FRM_USEBLIT is set, blit back the old
  2490.                                      screen contents, else do the FMD_FINISH
  2491.                                      to send out redraw messages.
  2492.  
  2493.                    cleanup      - 1. Free the blit buffer (if any).
  2494.                                   2. Call wnd_update(END_UPDATE).
  2495.  
  2496.                  The setup and cleanup phases are done on every call.  The
  2497.                  other phases are done when the corresponding action bit is
  2498.                  on in the options.
  2499.  
  2500.                  This function is fail-proof; if a blit buffer can't be
  2501.  
  2502.        
  2503.        ======================================================================
  2504.        GemFast v1.8                                                   Page 33
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.                  obtained, the dialog becomes unmovable, and redraw messages
  2514.                  are sent out after the dialog to restore the screen.  
  2515.  
  2516.        Source:   aesfuncs\frmdialo.c
  2517.  
  2518.  
  2519.  
  2520.  
  2521.  
  2522.  
  2523.  
  2524.  
  2525.  
  2526.  
  2527.  
  2528.  
  2529.  
  2530.  
  2531.  
  2532.  
  2533.  
  2534.  
  2535.  
  2536.  
  2537.  
  2538.  
  2539.  
  2540.  
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.        
  2569.        ======================================================================
  2570.        GemFast v1.8                                                   Page 34
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.        short frm_dsdial(char **strings, char **buttons, short explodeflag)
  2580.        short frm_dsdialog(long options, char **buttons, char **strings)
  2581.        ______________________________________________________________________
  2582.  
  2583.        Summary:  Dynamic string dialog.  Builds and conducts a dialog using
  2584.                  the specified strings and buttons.
  2585.  
  2586.        NOTE:     The frm_dsdial() format is outdated; use frm_dsdialog().
  2587.  
  2588.        Input:    The options parameter contains a bitmap of options as
  2589.                  described under Dialog Processing Options.
  2590.  
  2591.                  The buttons parameter is a pointer to an array of string
  2592.                  pointers.  Each element in the array is a pointer to the
  2593.                  string to display in one of the buttons.  You can display up
  2594.                  to 5 buttons.  The end of the array is marked by a NULL
  2595.                  string pointer.  If the buttons parameter is NULL, a single
  2596.                  button labeled "Continue" is displayed.  The buttons are
  2597.                  displayed left-to-right in the same order as  they are in
  2598.                  the array.
  2599.  
  2600.                  The strings parameter is a pointer to an array string
  2601.                  pointers.  Each element in the array is a pointer to a
  2602.                  string displayed within the body of the dialog.  You can
  2603.                  display up to 20 lines of text.  The end of the array is
  2604.                  marked by a NULL string pointer.  If the strings parameter
  2605.                  is NULL, a line containing "<no message>" is displayed in
  2606.                  the body of the dialog.
  2607.  
  2608.        Returns:  The index of the button the user clicked on to exit the
  2609.                  dialog, guaranteed to be in the range of 0 through 4.  The
  2610.                  leftmost button is 0.
  2611.  
  2612.        See Also: frm_printf() frm_defaults() frm_nldialog() frm_qtext()
  2613.  
  2614.        Details:  This is a fairly hostile function, so let me start by
  2615.                  recommending that you consider using frm_printf() or
  2616.                  frm_qtext() instead of calling this directly.
  2617.  
  2618.                  This function builds a dialog from the text and buttons you
  2619.                  specify, and conducts the dialog with the user.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.        
  2635.        ======================================================================
  2636.        GemFast v1.8                                                   Page 35
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.        Example:  You must create arrays to hold pointers to the button
  2646.                  strings and lines of text in the body.  The following
  2647.                  example displays a dialog with 3 buttons and several lines
  2648.                  of text:
  2649.  
  2650.                      char *buttons[] = {
  2651.                          "Cancel",   /* button 0             */
  2652.                          "Ignore",   /* button 1             */
  2653.                          "Retry",    /* button 2 (default)   */
  2654.                          NULL        /* mark end of array    */
  2655.                      };
  2656.  
  2657.                      char *text[] = {
  2658.                          "\x7F" "Error!",    /* center this line */
  2659.                          "Could not open configuration file.",
  2660.                          " ",
  2661.                          "Please select one of the following options:",
  2662.                          NULL                /* mark end of array    */
  2663.                      };
  2664.  
  2665.                      option = frm_dsdialog(FRM_DSL1TITLE, buttons, text);
  2666.  
  2667.        Source:   aesfuncs\frmdsdia.c
  2668.  
  2669.  
  2670.  
  2671.  
  2672.  
  2673.  
  2674.  
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.        
  2701.        ======================================================================
  2702.        GemFast v1.8                                                   Page 36
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.        short frm_eflag(OBJECT *ptree, short object, char *fmt, ...)
  2712.        ______________________________________________________________________
  2713.  
  2714.        Summary:  Visually flag a dialog object and display an error message.
  2715.  
  2716.        Input:    The ptree parameter is a pointer to the dialog tree.
  2717.  
  2718.                  The object parameter is the index of the object to be
  2719.                  flagged.
  2720.  
  2721.                  The fmt parameter is a printf-style format string containing
  2722.                  the error message.
  2723.  
  2724.                  The ... parameters are values to substitute into the format
  2725.                  string.
  2726.  
  2727.        Returns:  Zero on success or -1 on failure.
  2728.  
  2729.        See also: frm_printf()
  2730.  
  2731.        Details:  This function reports an error the user made in interacting
  2732.                  with a dialog.  For example, if a dialog contains a editable
  2733.                  field which must contain a value, and the user exits the
  2734.                  dialog without filling in that field, this function is an
  2735.                  ideal way to report the error to the user.
  2736.  
  2737.                  This function works with dialogs already visible on the
  2738.                  screen.  The object you specify is circled with a red
  2739.                  outline, and a box (a bit like a post-it note) appears
  2740.                  nearby containing the error message text.  When the user
  2741.                  hits a key or clicks the mouse button the screen is restored
  2742.                  to its original appearance and this function returns.
  2743.  
  2744.                  Any type of object can be specified as the object to be
  2745.                  flagged.  For example, if you have a collection of buttons
  2746.                  and the user must select at least one, specify the parent
  2747.                  box which contains the button group.
  2748.  
  2749.                  The error message can contain up to 20 lines of text.  The
  2750.                  longest line must not exceed the screen width.  As a
  2751.                  practical matter, it's a good idea to keep the message down
  2752.                  to 5 or 6 lines, each line no more than about one third to
  2753.                  one half the screen width.  Any line that starts with 0x7F
  2754.                  is centered in the display box (the 0x7F character is not
  2755.                  displayed).
  2756.  
  2757.                  It is possible for this routine to fail internally, if a VDI
  2758.                  workstation is not available or a blit buffer can't be
  2759.                  allocated.  In this case, an alert appears to tell the user
  2760.                  "An error has occurred with a dialog item you selected or
  2761.                  modified, but there are not enough system resources to
  2762.                  report the exact error."  If this happens, -1 is returned.
  2763.  
  2764.        Example:  To display a dialog, and ensure that the text edit field is
  2765.  
  2766.        
  2767.        ======================================================================
  2768.        GemFast v1.8                                                   Page 37
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.                  non-blank, the code might look like this:
  2778.  
  2779.                      frm_dialog(FRM_DSTART|FRM_DDRAW, mydialog, 0);
  2780.                      do  {
  2781.                          exitobj = frm_dialog(FRM_DDO, mydialog, EDITFIELD);
  2782.                          if (exitobj == OKAY && edit_field_data[0] == '\0') {
  2783.                              frm_eflag(mydialog, EDITFIELD,
  2784.                                  "\x7F" "You must supply a value between\n"
  2785.                                  "\x7F" " %d and %d for this field",
  2786.                                  lower_range, upper_range);
  2787.                              valid_entry = FALSE;
  2788.                          } else {
  2789.                              valid_entry = TRUE;
  2790.                          }
  2791.                      } while (!valid_entry);
  2792.                      frm_dialog(FRM_DFINISH, mydialog, 0);
  2793.  
  2794.        Source:   aesfuncs\frmeflag.c
  2795.  
  2796.  
  2797.  
  2798.  
  2799.  
  2800.  
  2801.  
  2802.  
  2803.  
  2804.  
  2805.  
  2806.  
  2807.  
  2808.  
  2809.  
  2810.  
  2811.  
  2812.  
  2813.  
  2814.  
  2815.  
  2816.  
  2817.  
  2818.  
  2819.  
  2820.  
  2821.  
  2822.  
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.        
  2833.        ======================================================================
  2834.        GemFast v1.8                                                   Page 38
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.        void frm_enableblit(void)
  2844.        ______________________________________________________________________
  2845.  
  2846.        Summary:  Enable the FRM_USEBLIT and FRM_MOVEABLE dialog options.
  2847.  
  2848.        Input:    Nothing.
  2849.  
  2850.        Returns:  Nothing.
  2851.  
  2852.        See Also: frm_defaults() frm_dialog()
  2853.  
  2854.        Details:  This function sets an internal pointer so that frm_dialog()
  2855.                  can call the grf_blit() function to save and restore the
  2856.                  screen.  You only have to call this function once, then from
  2857.                  that point on the FRM_USEBLIT flag is honored during dialog
  2858.                  processing.
  2859.  
  2860.                  Here's the deal... GemFast needed an option to use blitting
  2861.                  instead of redraw messages to save/restore the screen during
  2862.                  dialog processing.  But, if frm_dialog() were to contain a
  2863.                  direct call to grf_blit(), your linker would pull in all the
  2864.                  VDI code needed to support blitting, even if you didn't want
  2865.                  the FRM_USEBLIT option active in your program.  
  2866.  
  2867.                  So instead of making a direct call to grf_blit(), the
  2868.                  frm_dialog() function checks an internal pointer.  If the
  2869.                  pointer is NULL, blitting is disabled.  If the pointer is
  2870.                  not NULL, and the FRM_USEBLIT flag is set, frm_dialog()
  2871.                  calls the blit function indirectly through the pointer.
  2872.                  Since frm_dialog() has no direct reference to grf_blit(),
  2873.                  the linker won't automatically link in the blit code.
  2874.  
  2875.                  When you call this function, the pointer gets set to point
  2876.                  to the grf_blit() function.  Since that then causes a
  2877.                  reference to grf_blit(), your linker does pull in all the
  2878.                  blit code, but only because you specifically asked it to by
  2879.                  coding a call to this function.
  2880.  
  2881.        Source:   aesfuncs\frmenabl.c
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.        
  2899.        ======================================================================
  2900.        GemFast v1.8                                                   Page 39
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.        short frm_error(short errcode, char *buttons, char *fmt, ...)
  2910.        ______________________________________________________________________
  2911.  
  2912.        Summary:  Display a formatted message, followed by a standard error
  2913.                  message, in a dialog box.
  2914.  
  2915.        Input:    The errcode parameter is the numeric value of the error to
  2916.                  be reported.
  2917.  
  2918.                  The buttons parameter is a pointer to a string containing
  2919.                  the text of the buttons to display at the bottom of the
  2920.                  dialog box.  Up to five buttons can be displayed.  A newline
  2921.                  (\n) character terminates each button's text in the string
  2922.                  (you don't need a newline after the last button).  If you
  2923.                  pass a NULL pointer, you get a single button labeled
  2924.                  "Continue".
  2925.  
  2926.                  The fmt parameter is a printf-style format string.
  2927.  
  2928.                  The ... parameters are values to be substituted as specified
  2929.                  in the format string.
  2930.  
  2931.        Returns:  The index of the button the user clicked on to exit the
  2932.                  dialog, guaranteed to be in the range of 0 through 4.  The
  2933.                  leftmost button is 0.
  2934.  
  2935.        See Also: frm_printf() frm_defaults() frm_verror() frm_qerror()
  2936.  
  2937.        Details:  Basically, this is a frm_printf() function that adds an
  2938.                  error message to the end of your formatted message.  This
  2939.                  function passes the format string and ... parameters to
  2940.                  sprintf() to create a formatted message.  Then it passes the
  2941.                  errcode parameter to exterror() to get the message
  2942.                  describing that error, and adds it as a separate line below
  2943.                  the lines of your formatted message.  Then it passes the
  2944.                  whole huge text string, along with your buttons pointer, to
  2945.                  frm_nldialog() for display. 
  2946.  
  2947.        Example:  To report an error in opening a file, you might use:
  2948.  
  2949.                      FILE *thefile;
  2950.                      if (NULL == (thefile = fopen(filename, "r"))) {
  2951.                          return frm_error(errno, "Retry\nCancel", 
  2952.                                      "Can't open file %s",
  2953.                                       filename);
  2954.                      }
  2955.                  Which might yield an error message dialog such as:
  2956.                          +--------------------------------+
  2957.                          | Can't open file A:\GEMFAST.DOC | 
  2958.                          | File not found                 |
  2959.                          |                                |
  2960.                          |     | Retry |   | Cancel |     |
  2961.                          +--------------------------------+
  2962.        Source:   aesfuncs\frmerror.c
  2963.  
  2964.        
  2965.        ======================================================================
  2966.        GemFast v1.8                                                   Page 40
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.        short frm_menu(long options, OBJECT *ptree, short select_state)
  2976.        ______________________________________________________________________
  2977.  
  2978.        Summary:  Conduct a menu dialog using your object tree.
  2979.  
  2980.        Input:    The options parameter contains a bitmap of options as
  2981.                  described under Dialog Processing Options.
  2982.  
  2983.                  The ptree parameter is a pointer to the dialog tree.
  2984.  
  2985.                  The select_state parameter is the ob_state value the dialog
  2986.                  handler uses to indicate selection of an object.
  2987.  
  2988.        Returns:  The index of the object selected by the user, or NO_OBJECT
  2989.                  if the user didn't select any object.
  2990.  
  2991.        See also: frm_defaults() frm_dsmenu() frm_nlmenu() frm_qmenu()
  2992.  
  2993.        Details:  This function conducts a menu dialog.  The action of a menu
  2994.                  dialog is similar to that of GEM dropdown menus.  The menu
  2995.                  items are highlighted as the mouse moves through them, so
  2996.                  they are called "hot buttons".  (The items need not be
  2997.                  buttons, any type of object can be used; strings are the
  2998.                  most common hot button object type.)
  2999.  
  3000.                  You can use this function to implement "popup" menus that
  3001.                  can appear anywhere on the screen.  The popup menu looks
  3002.                  like a regular GEM dropdown menu, a box containing strings
  3003.                  that highlight as the mouse moves over them, except that it
  3004.                  can appear anywhere on the screen.  In addition to normal
  3005.                  popup menu dialogs, this function can conduct hybrid dialogs
  3006.                  that contain a mixture of normal exit buttons and menu-type
  3007.                  hot buttons.
  3008.  
  3009.                  For this function to work correctly, your menu dialog tree
  3010.                  has to be constructed with some simple rules in mind. 
  3011.                  Objects with the EXIT, TOUCHEXIT, or DEFAULT flag bits on
  3012.                  will behave as normal.  Objects flagged as SELECTABLE but
  3013.                  without the EXIT, TOUCHEXIT, or DEFAULT bits are the hot
  3014.                  buttons in the dialog; they will highlight as the mouse
  3015.                  crosses them, and a click on them will exit the dialog. The
  3016.                  dialog cannot contain selection (on/off) buttons, radio
  3017.                  buttons, or editable text fields.  Objects with the DISABLED
  3018.                  state bit on will not highlight or cause exit if clicked.
  3019.  
  3020.                  As the mouse passes over enabled hot button objects, they
  3021.                  are visually selected.  The value you pass for select_state
  3022.                  is ORed into the ob_state to visually select an object.  The
  3023.                  most common value should be SELECTED, but in some cases
  3024.                  (especially with colored objects) OUTLINED is a good choice.
  3025.  
  3026.                  If the FRM_DMUSTSELECT option is used, this function will
  3027.                  NOT return NO_OBJECT under any circumstances; only a click
  3028.                  on a hot button or normal exit object will end the dialog. 
  3029.  
  3030.        
  3031.        ======================================================================
  3032.        GemFast v1.8                                                   Page 41
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.                  Otherwise, if the user clicks on an object which is neither
  3042.                  a normal exit object nor a hot button, this function returns
  3043.                  NO_OBJECT, and if the FRM_MEXITPARENT or FRM_MEXITVICINITY
  3044.                  options are used and the mouse leaves the specified area,
  3045.                  this function returns NO_OBJECT.  
  3046.  
  3047.                  If the mouse button is down on entry to this function, it
  3048.                  waits for the button to be released before doing anything. 
  3049.                  When the user clicks on a TOUCHEXIT object, this function
  3050.                  returns with the mouse button still down, as usual.  When
  3051.                  the user clicks on a hot button object, this function
  3052.                  doesn't return until the user releases the mouse button.  
  3053.  
  3054.                  If the exit object was a normal EXIT or DEFAULT object, it
  3055.                  is deselected as per the rules for frm_dialog().  If the
  3056.                  exit object was a hot button, it remains selected both
  3057.                  visually and in the ob_state field.
  3058.  
  3059.        Source:   aesfuncs\aplmallo.c
  3060.  
  3061.  
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.        
  3097.        ======================================================================
  3098.        GemFast v1.8                                                   Page 42
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.        short frm_mkmoveable(OBJECT *ptree, short mover_object)
  3108.        ______________________________________________________________________
  3109.  
  3110.        Summary:  Makes a dialog moveable, and designates the mover object.
  3111.  
  3112.        Input:    The ptree parameter is a pointer to the object tree.
  3113.  
  3114.                  The mover_object parameter is the index of the object in the
  3115.                  tree which will serve as the mover object.
  3116.  
  3117.        Returns:  The object's ob_flags value before it was modified.
  3118.  
  3119.        See Also: frm_dialog()
  3120.  
  3121.        Details:  The frm_dialog() library routine allows users to drag a
  3122.                  dialog box around on the screen.  Use this function to
  3123.                  specify the object within the dialog which serves as the
  3124.                  mover.  
  3125.  
  3126.                  This function changes the ob_flags of the mover object,
  3127.                  turning off some bits and turning on others, as follows:
  3128.  
  3129.                    OFF - SELECTABLE DEFAULT EXIT EDITABLE RBUTTON HIDETREE
  3130.                    ON  - TOUCHEXIT FRM_MOVER
  3131.  
  3132.                  It does not change bits other than those listed.  The
  3133.                  FRM_MOVER bit is defined in GEMFAST.H.
  3134.  
  3135.                  When an object in a dialog tree is defined as the mover
  3136.                  object, that dialog is thereafter considered moveable on
  3137.                  every call to frm_dialog(), even when the FRM_MOVEABLE
  3138.                  option is not used in the call.  The FRM_MOVEABLE dialog
  3139.                  option makes a dialog moveable even when this function
  3140.                  hasn't been called to designate the mover object.  (The root
  3141.                  becomes the mover in that case.)
  3142.  
  3143.                  Use this function if you have designed a specific mover
  3144.                  object into a dialog with your resource editor.  Usually a
  3145.                  mover object is a G_BOXTEXT object, 50%-mask gray filled,
  3146.                  one gl_hbox high, placed across the top of the dialog with a
  3147.                  title string in it.  (IE, it looks like the move bar on a
  3148.                  window.)
  3149.  
  3150.        Source:   aesfuncs\frmmovab.c
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.        
  3163.        ======================================================================
  3164.        GemFast v1.8                                                   Page 43
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.        short frm_nldialog(long options, char *buttons, char *strings)
  3174.        ______________________________________________________________________
  3175.  
  3176.        Summary:  Newline-delimited dialog.  Builds and conducts a dialog
  3177.                  using the specified string and buttons.
  3178.  
  3179.        Input:    The options parameter contains a bitmap of options as
  3180.                  described under Dialog Processing Options.
  3181.  
  3182.                  The buttons parameter is a pointer to a string containing
  3183.                  the text of the buttons to display at the bottom of the
  3184.                  dialog box.  Up to five buttons can be displayed.  A newline
  3185.                  (\n) character terminates each button's text in the string. 
  3186.                  If you pass a NULL pointer, you get a single button labeled
  3187.                  "Continue".
  3188.  
  3189.                  The strings parameter is a pointer to a string containing
  3190.                  the text lines for the body of the dialog.  Up to 20 lines
  3191.                  of text can be displayed.  A newline character terminates
  3192.                  each line's text in the string. If you pass a NULL pointer,
  3193.                  you get a single line containing "<no message>".
  3194.  
  3195.        Returns:  The index of the button the user clicked on to exit the
  3196.                  dialog, guaranteed to be in the range of 0 through 4.  The
  3197.                  leftmost button is 0.
  3198.  
  3199.        See Also: frm_printf() frm_defaults() frm_qtext()
  3200.  
  3201.        Details:  This function builds a dialog from the text and buttons you
  3202.                  specify, and conducts the dialog with the user.  
  3203.  
  3204.                  You might use this function instead of frm_printf():
  3205.                    - If you don't need to substitute values into the output. 
  3206.                      There is more overhead associated with frm_printf(), in
  3207.                      terms of memory and speed.
  3208.                    - If your message will exceed the 2k limit imposed by
  3209.                      frm_printf().  (Of course, 2k of text is more than will
  3210.                      fit on a standard screen.)
  3211.  
  3212.                  This is slightly a friendlier version of the frm_dsdialog()
  3213.                  function.  Instead of constructing arrays of pointers to
  3214.                  strings, this allows you to use a single string with newline
  3215.                  characters indicating the line separations.
  3216.  
  3217.        Example:  The following example displays a dialog containing several
  3218.                  lines of text, and 3 buttons.
  3219.  
  3220.                      char buttons[] = "Cancel\Nignore\Nretry";
  3221.                      char text[] = 
  3222.                          "\x7F" "Error!\n"
  3223.                          "Cannot open configuration file.\n\n"
  3224.                          "Please select one of these options:\n";
  3225.                      choice = frm_nldialog(FRM_DSL1TITLE, buttons, text);
  3226.        Source:   aesfuncs\frmnldia.c
  3227.  
  3228.        
  3229.        ======================================================================
  3230.        GemFast v1.8                                                   Page 44
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.        short frm_nlmenu(long options, char *title, char *selections)
  3240.        ______________________________________________________________________
  3241.  
  3242.        Summary:  Build and conduct a menu dialog using your strings.
  3243.  
  3244.        Input:    The options parameter contains a bitmap of options as
  3245.                  described under Dialog Processing Options.
  3246.  
  3247.                  The title parameter is a pointer to a string which appears
  3248.                  in the menu dialog's title bar.  If a NULL pointer is
  3249.                  passed, the dialog box will have no title bar.
  3250.  
  3251.                  The selections parameter is a pointer to a string containing
  3252.                  the menu's selectable items.  Each selection is delimited by
  3253.                  a newline (\n) character.  (You don't need a newline after
  3254.                  the last selection.)
  3255.  
  3256.        Returns:  The 1-based index of the item selected, or 0 if the last
  3257.                  item was selected, or NO_OBJECT if no item was selected.
  3258.  
  3259.        See also: frm_defaults() frm_qmenu()
  3260.  
  3261.        Details:  This function builds and conducts a "popup" menu dialog.  If
  3262.                  you don't need to specify any options, the frm_qmenu()
  3263.                  function is easier to code.
  3264.  
  3265.                  The title string (if specified) appears centered and
  3266.                  underlined at the top of the dialog box.  The selection
  3267.                  strings appear, one per line, underneath the title.  Any
  3268.                  selection string that starts with 0x7F is centered (the 0x7F
  3269.                  character isn't displayed). Up to 20 selection lines can be
  3270.                  specified.  You must ensure that the title and selection
  3271.                  strings don't exceed the screen width.
  3272.  
  3273.                  The dialog box surrounding the title and strings will always
  3274.                  have a whitespace gutter of at least one character width on
  3275.                  each side of the widest selection line.  (If the title is
  3276.                  wider than the widest selection, the gutter will be more
  3277.                  than 1 character width).
  3278.  
  3279.                  The return value behavior is a bit complex, but it makes
  3280.                  sense if you follow a basic rule in designing your string
  3281.                  dialogs:  the last item on the menu should always be a Quit,
  3282.                  Cancel, or Exit type selection.  If the user selects the
  3283.                  last item, the return value is 0.  If the user clicks
  3284.                  outside the dialog, the return value is NO_OBJECT (-1). 
  3285.                  Otherwise the return value is the 1-based index of the
  3286.                  selection (first line = 1, second line = 2, etc).
  3287.  
  3288.                  If you specify the FRM_DMUSTSELECT option, the user is
  3289.                  forced to click on a menu selection to exit.  In this case,
  3290.                  the return value is guaranteed not to be NO_OBJECT.
  3291.  
  3292.        Source:   aesfuncs\frmnlmen.c
  3293.  
  3294.        
  3295.        ======================================================================
  3296.        GemFast v1.8                                                   Page 45
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.        short frm_printf(long options, char *buttons, char *fmt, ...)
  3306.        ______________________________________________________________________
  3307.  
  3308.        Summary:  Formats a message, builds a dialog box around it, and
  3309.                  conducts the dialog.
  3310.  
  3311.        Input:    The options parameter contains a bitmap of options as
  3312.                  described under Dialog Processing Options.
  3313.  
  3314.                  The buttons parameter is a pointer to a string containing
  3315.                  the text of the buttons to display at the bottom of the
  3316.                  dialog box.  Up to five buttons can be displayed.  A newline
  3317.                  (\n) character terminates each button's text in the string
  3318.                  (you don't need a newline after the last button).  If you
  3319.                  pass a NULL pointer, you get a single button labeled
  3320.                  "Continue".
  3321.  
  3322.                  The fmt parameter is a printf-style format string.
  3323.  
  3324.                  The ... parameters are values to be substituted as specified
  3325.                  in the format string.
  3326.  
  3327.        Returns:  The index of the button the user clicked on to exit the
  3328.                  dialog, guaranteed to be in the range of 0 through 4.  The
  3329.                  leftmost button is 0.
  3330.  
  3331.        See Also: frm_defaults() frm_vprintf() 
  3332.  
  3333.        Details:  This function allocates a 2k buffer to format the string
  3334.                  into.  It passes the specified format string and ...
  3335.                  parameters to sprintf() to create a formatted message.
  3336.                  Newline (\n) characters in the result of the sprintf()
  3337.                  formatting delimit the lines as displayed in the dialog.
  3338.  
  3339.        Source:   aesfuncs\frmprtf.c
  3340.  
  3341.  
  3342.  
  3343.  
  3344.  
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.        
  3361.        ======================================================================
  3362.        GemFast v1.8                                                   Page 46
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.        short frm_progress(long options, short increments, 
  3372.                           char *button, char *fmt, ...)
  3373.        ______________________________________________________________________
  3374.  
  3375.        Summary:  Conducts a progress display with a thermometer bar,
  3376.                  formatted text, and an optional abort button.
  3377.  
  3378.        Input:    The options parameter contains a bitmap of options and
  3379.                  actions.  The options are described under Dialog Processing
  3380.                  Options.  In addition, you must OR in exactly one of the
  3381.                  following actions:
  3382.  
  3383.                    FRM_PSTART  - Initialize and draw the dialog.
  3384.                    FRM_PUPDATE - Update the progress display.
  3385.                    FRM_PFINISH - Close and cleanup the dialog.
  3386.  
  3387.                  The increments parameter is interpreted differently,
  3388.                  depending on the action, as described below.
  3389.  
  3390.                  The button parameter is a pointer to a string containing the
  3391.                  text of the abort button in the dialog.  If NULL, the dialog
  3392.                  will not contain an abort button.
  3393.  
  3394.                  The fmt parameter is a printf-style format string.
  3395.  
  3396.                  The ... parameters are values to be substituted as specified
  3397.                  in the format string.
  3398.  
  3399.        Returns:  For FRM_PSTART, 0 on success or a negative error code.  
  3400.                  For FRM_PUPDATE, TRUE (1) if the user clicked on the abort
  3401.                  button, or FALSE (0) if not.
  3402.                  For FRM_PFINISH, there is no return value.
  3403.  
  3404.        See Also: frm_printf() frm_defaults() frm_vprogress() 
  3405.  
  3406.        Details:  This function dynamically constructs a dialog around your
  3407.                  formatted text, appropriate to keeping the user informed of
  3408.                  the progress of some ongoing task.  The dialog can
  3409.                  optionally contain an abort button if you want the user to
  3410.                  be able to abort the task.  The progress can be indicated by
  3411.                  either or both of two methods:  a graphical thermometer bar
  3412.                  which fills in as progress is made, and a text line in the
  3413.                  body of the dialog that explains the progress with words.
  3414.  
  3415.                  To start the progress dialog, use the FRM_PSTART action
  3416.                  flag.  When you start the dialog, the increments parameter
  3417.                  indicates how many 'ticks' you intend to step the
  3418.                  thermometer bar through.  If this is zero, the dialog will
  3419.                  not have a thermometer bar.  (See the description of
  3420.                  xob_thermo_create() for more details on using a thermometer
  3421.                  bar.)  If you pass a NULL button pointer when you start the
  3422.                  dialog, there won't be an abort button in the dialog,
  3423.                  otherwise the text you specify is used in the button.  The
  3424.                  fmt parameter and values following it are processed as for
  3425.  
  3426.        
  3427.        ======================================================================
  3428.        GemFast v1.8                                                   Page 47
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.                  other formatted text dialogs.  If you intend to use words as
  3438.                  well as the thermometer bar to indicate progress, the words
  3439.                  are displayed in place of the last line of formatted text in
  3440.                  the body of the dialog.  It doesn't matter if the last line
  3441.                  is initially empty.
  3442.  
  3443.                  To update the progress display, use the FRM_PUPDATE action
  3444.                  flag.  When updating the display, the increments parameter
  3445.                  can have the following values:
  3446.                    
  3447.                    OBJ_TINCREMENT    -   Advance the thermometer bar by one.
  3448.                    Zero              -   Do not change the thermometer bar.
  3449.                    Greater than zero -   Set the thermometer bar increment
  3450.                                          count to the specified number.
  3451.  
  3452.                  The button parameter is ignored for FRM_PUPDATE.  If the fmt
  3453.                  parameter is NULL, no change is made to the text in the
  3454.                  dialog.  If non-NULL, it is a printf-style format string,
  3455.                  and ... arguments may follow it.  In this case, the text is
  3456.                  formatted into a static 128-byte buffer, and is then
  3457.                  displayed in the last line of text in the dialog body
  3458.                  (replacing any existing characters on that line.)  It is
  3459.                  your responsibility to ensure that the new line is less than
  3460.                  128 characters after formatting, and that it is no wider
  3461.                  than the widest line in the existing text.  (IE, the dialog
  3462.                  cannot be made wider once FRM_PSTART has painted it.)  If
  3463.                  the last line of text in the initial dialog was centered,
  3464.                  then all updates will be centered.  (Do NOT specify the 0x7F
  3465.                  centering flag at the start of the update string in fmt.)
  3466.  
  3467.                  To end the dialog and remove it from the screen, use the
  3468.                  FRM_PFINISH action flag.  All other parameters are ignored.
  3469.  
  3470.                  If you specify an abort button, be sure to check the return
  3471.                  value from every progress display update.
  3472.  
  3473.                  Be aware that if the FRM_MOVEABLE dialog option is in
  3474.                  effect, or if you specify an abort button, a progress update
  3475.                  call can take an indefinite amount of time.  (Because the
  3476.                  user could spend any amount of time dragging the dialog
  3477.                  around or clicking but not releasing the abort exit button.)
  3478.  
  3479.                  You can update both the thermometer and text progress
  3480.                  display on a single call, update just one or the other, or
  3481.                  not update either of them.  You might use the latter to poll
  3482.                  for an abort without changing the display when your
  3483.                  incremental steps take a long time.
  3484.  
  3485.  
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.        
  3493.        ======================================================================
  3494.        GemFast v1.8                                                   Page 48
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.        Example:  Suppose your program formats a floppy disk.  You want to
  3504.                  report the current track and side with words, and update the
  3505.                  thermometer after both sides of each track are done.  You
  3506.                  might use code such as the following:
  3507.  
  3508.                  char trackmsg[] = "Formatting Track: %d Side: %d";
  3509.                  char mainmsg[]  = "Formatting floppy drive %c           \n"
  3510.                                    "\n"      // empty line
  3511.                                    "\x7F "   // track message centered here
  3512.                                    ;
  3513.  
  3514.                  frm_progress(FRM_PSTART, ntracks, NULL, trackmsg, drive);
  3515.                  for (track = 0; track < ntracks; ++track) {
  3516.                      frm_progress(FRM_PUPDATE, 0, NULL, trackmsg, track, 0);
  3517.                      format_it(drive, track, 0);
  3518.                      frm_progress(FRM_PUPDATE, 0, NULL, trackmsg, track, 1);
  3519.                      format_it(drive, track, 1);
  3520.                      frm_progress(FRM_PUPDATE, OBJ_TINCREMENT, NULL, NULL);
  3521.                  }
  3522.                  frm_progress(FRM_PFINISH, 0, NULL, NULL);
  3523.  
  3524.                  Notice that the first line of the main dialog text contains
  3525.                  enough extra spaces to ensure that it will be wider than the
  3526.                  widest possible trackmsg display.  Also notice that the last
  3527.                  line (where the track/side message will appear) has the \x7F
  3528.                  centering flag specified in the original display text, not
  3529.                  in the update text, and also that the \x7F is followed by a
  3530.                  space (since there has to be something besides the \x7F on
  3531.                  the line for it to be noticed as a line).
  3532.  
  3533.        Source:   aesfuncs\frmprogr.c
  3534.  
  3535.  
  3536.  
  3537.  
  3538.  
  3539.  
  3540.  
  3541.  
  3542.  
  3543.  
  3544.  
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.        
  3559.        ======================================================================
  3560.        GemFast v1.8                                                   Page 49
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.        short frm_qchoice(char *buttons, char *fmt, ...)
  3570.        ______________________________________________________________________
  3571.  
  3572.        Summary:  Build and conduct dialog with formatted message and up to
  3573.                  five buttons.
  3574.  
  3575.        Input:    The buttons parameter is a pointer to a string containing
  3576.                  the text of the buttons to display at the bottom of the
  3577.                  dialog box.  Up to five buttons can be displayed.  A newline
  3578.                  (\n) character terminates each button's text in the string
  3579.                  (you don't need a newline after the last button).
  3580.  
  3581.                  The fmt parameter is a printf-style format string.
  3582.  
  3583.                  The ... parameters are values to be substituted as specified
  3584.                  in the format string.
  3585.  
  3586.        Returns:  The index of the button the user clicked on to exit the
  3587.                  dialog, guaranteed to be in the range of 0 through 4.  The
  3588.                  leftmost button is 0.
  3589.  
  3590.        See also: frm_printf() frm_defaults() frm_qtext()
  3591.  
  3592.        Details:  This is just a frm_printf() function without an options
  3593.                  parameter.  Think of it as an alert box with no icon and up
  3594.                  to five buttons.
  3595.  
  3596.        Source:   aesfuncs\frmqchoi.c
  3597.  
  3598.  
  3599.  
  3600.  
  3601.  
  3602.  
  3603.  
  3604.  
  3605.  
  3606.  
  3607.  
  3608.  
  3609.  
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.        
  3625.        ======================================================================
  3626.        GemFast v1.8                                                   Page 50
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.        short frm_qerror(short err, char *fmt, ...)
  3636.        ______________________________________________________________________
  3637.  
  3638.        Summary:  Display formatted error message with Continue button.
  3639.  
  3640.        Input:    The err parameter is the numeric code of the error to be
  3641.                  reported.
  3642.  
  3643.                  The fmt parameter is a printf-style format string.
  3644.  
  3645.                  The ... parameters are values to be substituted as specified
  3646.                  in the format string.
  3647.  
  3648.        Returns:  The same value passed as the err parameter.
  3649.  
  3650.        See also: frm_printf() frm_defaults() frm_error() frm_qfatal() 
  3651.  
  3652.        Details:  This is a frm_error() function with a default exit button
  3653.                  labeled Continue, and a different kind of return value.  See
  3654.                  the details of frm_error() for more information on the error
  3655.                  message lookup and formatting.
  3656.  
  3657.                  Use frm_qerror() when the user doesn't have any corrective
  3658.                  action options or choices about what to do next, but the
  3659.                  program will continue to run.
  3660.  
  3661.                  Use frm_qfatal() when the error is so serious that the
  3662.                  program will shut itself down after the user acknowledges
  3663.                  the message.
  3664.  
  3665.                  Use frm_error() when you are able to present multiple
  3666.                  options (such as Cancel | Retry) to the user.
  3667.  
  3668.                  When you are just reporting an error that can't be corrected
  3669.                  or otherwise influenced by the user, frm_qerror() or
  3670.                  frm_qfatal() are better, because they return the same error
  3671.                  code you passed.  This lets you write statements such as:
  3672.  
  3673.                      if (Success != (err = something_that_can_fail())) {
  3674.                          return frm_qerror(err, "Can't do something!");
  3675.                      }
  3676.  
  3677.                  So you can both report the error and return the error status
  3678.                  to the calling routine in a single statement.
  3679.  
  3680.        Source:   aesfuncs\frmqerr.c
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.        
  3691.        ======================================================================
  3692.        GemFast v1.8                                                   Page 51
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.        short frm_qfatal(short err, char *fmt, ...)
  3702.        ______________________________________________________________________
  3703.  
  3704.        Summary:  Display formatted error message with Fatal button.
  3705.  
  3706.        Input:    The err parameter is the numeric code of the error to be
  3707.                  reported.
  3708.  
  3709.                  The fmt parameter is a printf-style format string.
  3710.  
  3711.                  The ... parameters are values to be substituted as specified
  3712.                  in the format string.
  3713.  
  3714.        Returns:  The same value passed as the err parameter.
  3715.  
  3716.        See also: frm_printf() frm_defaults() frm_error() frm_qfatal() 
  3717.  
  3718.        Details:  This is a frm_error() function with a default exit button
  3719.                  labeled Fatal and a different kind of return value.  See the
  3720.                  details of frm_error() for more information on the error
  3721.                  message lookup and formatting.
  3722.  
  3723.                  Use frm_qerror() when the user doesn't have any corrective
  3724.                  action options or choices about what to do next, but the
  3725.                  program will continue to run.
  3726.  
  3727.                  Use frm_qfatal() when the error is so serious that the
  3728.                  program will shut itself down after the user acknowledges
  3729.                  the message.
  3730.  
  3731.                  Use frm_error() when you are able to present multiple
  3732.                  options (such as Cancel | Retry) to the user.
  3733.  
  3734.                  When you are just reporting an error that can't be corrected
  3735.                  or otherwise influenced by the user, frm_qerror() or
  3736.                  frm_qfatal() are better, because they return the same error
  3737.                  code you passed.  This lets you write statements such as:
  3738.  
  3739.                      if (Success != (err = something_that_can_fail())) {
  3740.                          return frm_qerror(err, "Can't do something!");
  3741.                      }
  3742.  
  3743.                  So you can both report the error and return the error status
  3744.                  to the calling routine in a single statement.
  3745.  
  3746.        Source:   aesfuncs\frmqerr.c
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.        
  3757.        ======================================================================
  3758.        GemFast v1.8                                                   Page 52
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.        short frm_qmenu(char *title, char *selections)
  3768.        ______________________________________________________________________
  3769.  
  3770.        Summary:  Build and conduct a menu dialog using your strings.
  3771.  
  3772.        Input:    The title parameter is a pointer to a string which appears
  3773.                  in the menu dialog's title bar.  If a NULL pointer is
  3774.                  passed, the dialog box will have no title bar.
  3775.  
  3776.                  The selections parameter is a pointer to a string containing
  3777.                  the menu's selectable items.  Each selection is delimited by
  3778.                  a newline (\n) character.  (You don't need a newline after
  3779.                  the last selection.)
  3780.  
  3781.        Returns:  The 1-based index of the item selected, or 0 if the last
  3782.                  item was selected, or NO_OBJECT if no item was selected.
  3783.  
  3784.        See also: frm_defaults() frm_nlmenu()
  3785.  
  3786.        Details:  This is just a frm_nlmenu() function without an options
  3787.                  parameter.  See the details for frm_nlmenu() for a
  3788.                  description of the dialog formatting.  When the default
  3789.                  options are good enough for your popup menu, use this
  3790.                  function.
  3791.  
  3792.        Source:   aesfuncs\frmqmenu.c
  3793.  
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.        
  3823.        ======================================================================
  3824.        GemFast v1.8                                                   Page 53
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.        void frm_qtext(char *fmt, ...)
  3834.        ______________________________________________________________________
  3835.  
  3836.        Summary:  Build and conduct dialog with formatted message and Continue
  3837.                  button.
  3838.  
  3839.        Input:    The fmt parameter is a printf-style format string.
  3840.  
  3841.                  The ... parameters are values to be substituted as specified
  3842.                  in the format string.
  3843.  
  3844.        Returns:  Nothing.
  3845.  
  3846.        See also: frm_printf() frm_defaults()
  3847.  
  3848.        Details:  This is just a frm_printf() function without options or
  3849.                  buttons parameters.  See the details for frm_printf().
  3850.  
  3851.                  This function is especially handy for debugging GEM programs
  3852.                  during development, since you can easily insert calls to it:
  3853.  
  3854.                      frm_qtext("At this point, rectangle = %d %d %d %d",
  3855.                          *pcliprect);
  3856.  
  3857.                  But it's also useful whenever you need to communicate with
  3858.                  the user and the default options and a Continue exit button
  3859.                  are good enough.
  3860.  
  3861.        Source:   aesfuncs\frmqtext.c
  3862.  
  3863.  
  3864.  
  3865.  
  3866.  
  3867.  
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.  
  3874.  
  3875.  
  3876.  
  3877.  
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.        
  3889.        ======================================================================
  3890.        GemFast v1.8                                                   Page 54
  3891.  
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.        short frm_question(char *fmt, ...)
  3900.        ______________________________________________________________________
  3901.  
  3902.        Summary:  Build and conduct a formatted dialog with Yes and No exit
  3903.                  buttons.
  3904.  
  3905.        Input:    The fmt parameter is a printf-style format string.
  3906.  
  3907.                  The ... parameters are values to be substituted as specified
  3908.                  in the format string.
  3909.  
  3910.        Returns:  FALSE (0) if the user selected No, or TRUE (1) if the user
  3911.                  selected Yes.
  3912.  
  3913.        See also: frm_printf() frm_defaults()
  3914.  
  3915.        Details:  This is just a frm_printf() function without an options
  3916.                  parameter, and with two buttons labeled Yes and No.  See the
  3917.                  frm_printf() for details on the message formatting.  
  3918.  
  3919.                  If the FRM_DEFAULTLEFT option is in effect, the Yes button
  3920.                  appears on the left, and it is the default exit button. 
  3921.                  Otherwise, the No button appears on the left, and neither
  3922.                  button will be a default exit button.
  3923.  
  3924.        Source:   aesfuncs\frmquest.c
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.  
  3935.  
  3936.  
  3937.  
  3938.  
  3939.  
  3940.  
  3941.  
  3942.  
  3943.  
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.        
  3955.        ======================================================================
  3956.        GemFast v1.8                                                   Page 55
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.        void frm_sizes(OBJECT *ptree, GRECT *prect)
  3966.        ______________________________________________________________________
  3967.  
  3968.        Summary:  Calculate the rectangle a dialog will occupy when displayed
  3969.                  on the screen.
  3970.  
  3971.        Input:    The ptree parameter is a pointer to the object tree you want
  3972.                  the sizes of.
  3973.  
  3974.                  The prect parameter is a pointer to a GRECT structure into
  3975.                  which the screen location and sizes are returned.
  3976.  
  3977.        Returns:  Nothing.
  3978.  
  3979.        See Also: obj_clcalc()
  3980.  
  3981.        Details:  This function provides the info you need to conduct the
  3982.                  form_dial() parts of a dialog.  Normally, the form_center()
  3983.                  function is used to center the dialog and obtain the
  3984.                  resulting screen rectangle.  When you want to display a
  3985.                  dialog that isn't centered, use this function instead of
  3986.                  form_center() to obtain the rectangle to pass to
  3987.                  form_dial().
  3988.  
  3989.        NOTE:     This function is implemented as a macro in GEMFAST.H.  The
  3990.                  macro remaps the call to obj_clcalc(), supplying a couple
  3991.                  dummy parms in the process.
  3992.  
  3993.        Source:   aesfuncs\objclcal.c (via macro in GEMFAST.H)
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.        
  4021.        ======================================================================
  4022.        GemFast v1.8                                                   Page 56
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.        short frm_verror(short errcode, char **buttons, char *fmt,
  4032.                         va_list args)
  4033.        ______________________________________________________________________
  4034.  
  4035.  
  4036.        NOTE:     This function is identical to frm_error(), except that it
  4037.                  takes a va_list pointer instead of directly accepting the
  4038.                  variable argument list.  If this doesn't mean anything to
  4039.                  you, you probably don't need this function.
  4040.  
  4041.                  See your compiler's runtime library manual, and check out
  4042.                  the difference between your printf() and vprintf()
  4043.                  functions.  That's the same as the difference between
  4044.                  frm_error() and frm_verror().
  4045.  
  4046.        Source:   aesfuncs\frmverro.c
  4047.  
  4048.  
  4049.  
  4050.        short frm_vprintf(long options, char **buttons, char *fmt,
  4051.                          va_list args)
  4052.        ______________________________________________________________________
  4053.  
  4054.        NOTE:     This function is identical to frm_printf(), except that it
  4055.                  takes a va_list pointer instead of directly accepting the
  4056.                  variable argument list.  If this doesn't mean anything to
  4057.                  you, you probably don't need this function. 
  4058.  
  4059.                  See your compiler's runtime library manual, and check out
  4060.                  the difference between your printf() and vprintf()
  4061.                  functions.  That's the same as the difference between
  4062.                  frm_printf() and frm_vprintf().
  4063.  
  4064.        Source:   aesfuncs\frmvprtf.c
  4065.  
  4066.  
  4067.  
  4068.  
  4069.        short frm_vprogress(long options, short increments, 
  4070.                           char *button, char *fmt, va_list args)
  4071.        ______________________________________________________________________
  4072.  
  4073.        NOTE:     This function is identical to frm_progress(), except that it
  4074.                  takes a va_list pointer instead of directly accepting the
  4075.                  variable argument list.  If this doesn't mean anything to
  4076.                  you, you probably don't need this function. 
  4077.  
  4078.                  See your compiler's runtime library manual, and check out
  4079.                  the difference between your printf() and vprintf()
  4080.                  functions.  That's the same as the difference between
  4081.                  frm_progress() and frm_vprogress().
  4082.  
  4083.        Source:   aesfuncs\frmprogr.c
  4084.  
  4085.  
  4086.        
  4087.        ======================================================================
  4088.        GemFast v1.8                                                   Page 57
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.        File Selector Library
  4098.  
  4099.  
  4100.                  The file selector library contains functions to conduct file
  4101.                  selector and related dialogs for you.
  4102.  
  4103.  
  4104.  
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.  
  4118.  
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.        
  4153.        ======================================================================
  4154.        GemFast v1.8                                                   Page 58
  4155.  
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.        short fsel_exinput(char *path, char *file, short &exitbutton,
  4164.                           char *prompt)
  4165.        ______________________________________________________________________
  4166.  
  4167.        Summary:  Standard system file selector, with prompting and full
  4168.                  emulation on pre-TOS 1.04 systems.
  4169.  
  4170.        Input:    The inputs are identical to the standard fsel_input()
  4171.                  function, except that an extra parameter, prompt allows you
  4172.                  to provide a prompt string of up to 38 characters.
  4173.  
  4174.        Returns:  TRUE (1) if the user exited via OKAY, or FALSE (0) if the
  4175.                  user exited via CANCEL.
  4176.  
  4177.        See Also:
  4178.  
  4179.        Details:  Atari added the fsel_exinput() prompted file selector
  4180.                  starting with TOS version 1.04.  It allows you to specify a
  4181.                  prompt string to appear in the file selector, and it behaves
  4182.                  slightly differently than the original selector (saves
  4183.                  current default path, etc).
  4184.  
  4185.                  This implementation of fsel_exinput() is compatible with all
  4186.                  TOS versions.  It checks the TOS version, and passes the
  4187.                  call directly to the AES on later versions, or emulates the
  4188.                  new functionality on older AES versions.
  4189.  
  4190.                  While the emulation code increases the size of your
  4191.                  application somewhat, the user-friendliness of the prompted
  4192.                  file selector is a nice feature to have.  I strongly
  4193.                  recommend using this function rather than fsel_input().
  4194.  
  4195.        Source:   aesbind\aesfsel2.s
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.        
  4219.        ======================================================================
  4220.        GemFast v1.8                                                   Page 59
  4221.  
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.  
  4229.        short fsel_sminput(char *path, char *file, short &exitbutton,
  4230.                           char *prompt)
  4231.        ______________________________________________________________________
  4232.  
  4233.        Summary:  Standard system file selector, with prompting and partial
  4234.                  emulation on pre-TOS 1.04 systems.
  4235.  
  4236.        Input:    The inputs are identical to the standard fsel_input()
  4237.                  function, except that an extra parameter, prompt allows you
  4238.                  to provide a prompt string of up to 38 characters.
  4239.  
  4240.        Returns:  TRUE (1) if the user exited via OKAY, or FALSE (0) if the
  4241.                  user exited via CANCEL.
  4242.  
  4243.        See Also: fsel_exinput()
  4244.  
  4245.        Details:  This function is similar to fsel_exinput(), except that it
  4246.                  emulates only the prompting feature on older TOS versions;
  4247.                  other behaviors of the new file selector are not emulated. 
  4248.                  This can make your application a bit smaller, and is
  4249.                  appropriate mainly for a desk accessory where a few hundred
  4250.                  bytes of code is significant.
  4251.  
  4252.        Source:   aesbind\aesfsel3.s
  4253.  
  4254.  
  4255.  
  4256.  
  4257.  
  4258.  
  4259.  
  4260.  
  4261.  
  4262.  
  4263.  
  4264.  
  4265.  
  4266.  
  4267.  
  4268.  
  4269.  
  4270.  
  4271.  
  4272.  
  4273.  
  4274.  
  4275.  
  4276.  
  4277.  
  4278.  
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.        
  4285.        ======================================================================
  4286.        GemFast v1.8                                                   Page 60
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.  
  4295.        short fsl_dialog(long options, char *pfullname, char *ppath,
  4296.                         char *pwild, char *pprompt)
  4297.        ______________________________________________________________________
  4298.  
  4299.        Summary:  Conduct a complete file selector dialog, return the
  4300.                  resulting full device/path/file name.
  4301.  
  4302.        Input:    The options parameter specifies options as a bitmap; OR
  4303.                  together one or more of the following:
  4304.  
  4305.                    FSL_NORMAL     -  A placeholder value, equal to zero.
  4306.                    FSL_FNOPTIONAL -  Selection of a file name is optional.
  4307.                    FSL_PATHONLY   -  Return only the path.
  4308.  
  4309.                  The pfullname parameter points to a buffer into which the
  4310.                  final full device/path/file name is returned.  This pointer
  4311.                  must not be NULL.
  4312.  
  4313.                  The ppath parameter points to a buffer containing the
  4314.                  device/path/wildcard string to display initially in the
  4315.                  dialog.  The final device/path/wildcard ends up in this
  4316.                  buffer after the call. If a NULL pointer is passed, a
  4317.                  default buffer internal to the function is used.
  4318.  
  4319.                  The pwild parameter, if non-NULL, points to a wildcard mask
  4320.                  string to be forced onto the end of the ppath string before
  4321.                  displaying the dialog. 
  4322.  
  4323.                  The pprompt parameter points to the prompt string to display
  4324.                  in the file selector.  If a NULL pointer is passed, a
  4325.                  default prompt ("Select File") is used.
  4326.  
  4327.  
  4328.        Returns:  TRUE (1) if the user exited via OKAY and the input passed
  4329.                  the validations specified in the options.  FALSE (0) if the
  4330.                  user exited via CANCEL, or any validation failed.  If this
  4331.                  function returns FALSE, the buffers pointed to by pfullname
  4332.                  and ppath are not modified.
  4333.  
  4334.        See Also:
  4335.  
  4336.        Details:  This function simplifies file selector interaction with the
  4337.                  user.  It is somewhat complex, because it attempts to
  4338.                  include all the functionality a complex program would need. 
  4339.                  But most of the complexity is covered with simple defaults,
  4340.                  and the function is pretty easy to use.
  4341.  
  4342.                  If you specify the FSL_FNOPTIONAL flag, this function does
  4343.                  not ensure the presence of a filename in the selection made
  4344.                  by the user; the return value indicates only whether the
  4345.                  user clicked on OKAY or CANCEL.  (Normally, this function
  4346.                  returns zero if no filename was selected; ie, a missing
  4347.                  filename is treated as a CANCEL.)
  4348.  
  4349.  
  4350.        
  4351.        ======================================================================
  4352.        GemFast v1.8                                                   Page 61
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.  
  4361.                  If you specify the FSL_PATHONLY flag, not only is the
  4362.                  filename entry optional, this function removes any filename
  4363.                  and returns just the path part.  The path is guaranteed to
  4364.                  have a trailing '\' character.
  4365.  
  4366.                  I recommend that you use 128-character buffers to hold
  4367.                  pathnames.  This function does no checking of pathname
  4368.                  lengths or truncation of long names, but 128 characters is
  4369.                  the accepted standard for GEMDOS programming.
  4370.  
  4371.                  About the ppath string:  If this pointer is NULL, a 128-byte
  4372.                  static internal buffer is used instead.  If the string is
  4373.                  empty, this function automatically initializes it to the
  4374.                  current device and path.  If the string is not empty, is
  4375.                  MUST have either a wildcard string on the end of it, or a
  4376.                  trailing '\' character.  (If it contains a path without a
  4377.                  wildcard or trailing '\', the last node of the pathname is
  4378.                  assumed to be a wildcard, and the user will get real
  4379.                  confused.)  If it has a trailing '\', a default wildcard of
  4380.                  "*.*" is added.
  4381.  
  4382.                  About the pwild string:  After processing the ppath string
  4383.                  as described above, the pwild pointer is checked.  If it is
  4384.                  non-NULL, then the wildcard on the end of the ppath string
  4385.                  is replaced with the pwild string.
  4386.  
  4387.                  Once the ppath and pwild strings are processed,
  4388.                  fsel_exinput() is invoked.  If the user selects CANCEL, this
  4389.                  function returns FALSE immediately.  If the user selects
  4390.                  OKAY, the presence of a filename is verified (unless the
  4391.                  options say the filename is optional).  If the filename
  4392.                  validation passes, the path and wildcard shown in the file
  4393.                  selector are copied to the ppath buffer.  Then the full
  4394.                  device/path/filename string is assembled into your pfullname
  4395.                  buffer, and TRUE is returned.
  4396.  
  4397.                  Now we come to the religious part of this description: 
  4398.                  usage recommendations.  I hate the way folks use file
  4399.                  selectors in programs, and I want to establish one
  4400.                  overriding rule:  the user should always see the same path
  4401.                  s/he saw last time in the file selector.  That can be
  4402.                  modified a bit in some situations, as you'll see...
  4403.  
  4404.                  For a simple program that only deals with one type of file,
  4405.                  I recommend that you use a NULL ppath and pwild pointer, and
  4406.                  let this function do all the work.  The first time you call
  4407.                  this function, it self-initializes to the current path. 
  4408.                  After that, the user will always see the same thing s/he
  4409.                  last saw.  If you want to be just a little trickier, pass an
  4410.                  appropriate pwild pointer the first time you call this
  4411.                  function, so that the user starts out seeing the right kind
  4412.                  of files.  Then pass a NULL pwild pointer on subsequent
  4413.                  calls, so that if the user decided to look at a different
  4414.                  type of file, it stays that way.
  4415.  
  4416.        
  4417.        ======================================================================
  4418.        GemFast v1.8                                                   Page 62
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.  
  4427.                  Sometimes a program only deals with a certain kind of file. 
  4428.                  Perhaps it can only read .RSC files, and only write .XYZ
  4429.                  files.  In this case, use a NULL ppath pointer, but non-NULL
  4430.                  pwild pointers in your calls.  If the user wants to try
  4431.                  something other than a .RSC file, it won't be prevented, but
  4432.                  will be strongly discouraged.  However, don't do this sort
  4433.                  of thing if you expect to read .TXT files.  Maybe the user
  4434.                  has renamed all the .TXT files to .DOC, and it's not your
  4435.                  job to discourage that by facistly forcing the wildcard on
  4436.                  every call.
  4437.  
  4438.                  For a complex program that deals with several types of
  4439.                  files, it can make sense to maintain several current paths. 
  4440.                  Perhaps you store graphics images in one subdirectory, sound
  4441.                  bites in another, and script files in a third place.  If the
  4442.                  user does a Load Image, then later does a Load Script, it
  4443.                  doesn't make sense to have the script file selector open up
  4444.                  to the image path just because that's what the user last
  4445.                  saw.  It would make more sense to open the selector up to
  4446.                  the path the user saw last time s/he did something with
  4447.                  script files.  For this situation, use a non-NULL ppath
  4448.                  pointer.  You can have several path buffers in your program
  4449.                  (script_path, image_path, etc).  Then just pass the same
  4450.                  path buffer every time you want to select that type of file,
  4451.                  and the user will always see the right path for that
  4452.                  filetype.
  4453.  
  4454.                  When you maintain several path buffers for different types
  4455.                  of files, you can start out with all the path buffers empty. 
  4456.                  The first time you pass the empty buffer to this function,
  4457.                  it'll get initialized to the current device and path.  Or,
  4458.                  you can pre-initialize the buffers yourself during program
  4459.                  startup (perhaps loading them from a config file).  If you
  4460.                  initialize them yourself, remember to ensure that they end
  4461.                  in a wildcard mask or have a trailing '\' character.
  4462.  
  4463.                  The thing to avoid at all costs is using a non-NULL ppath
  4464.                  pointer and explicitly reloading a path into that buffer
  4465.                  before each call to this function.  I've used programs that
  4466.                  explicitly loaded A:\*.* into the path before each call to
  4467.                  the file selector.  But I never used any of them for very
  4468.                  long; they've all ended up in the trash.
  4469.  
  4470.                  [End of sermon]
  4471.  
  4472.        Source:   aesfuncs\fsldialo.c
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.        
  4483.        ======================================================================
  4484.        GemFast v1.8                                                   Page 63
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.        Graphics Library
  4494.  
  4495.  
  4496.                  The graphics library contains functions to help you deal
  4497.                  with the graphics screen and the mouse.  It includes
  4498.                  functions to get and set the current mouse shape, and
  4499.                  functions to easily blit areas of the screen from and to
  4500.                  memory buffers.
  4501.  
  4502.  
  4503.  
  4504.  
  4505.  
  4506.  
  4507.  
  4508.  
  4509.  
  4510.  
  4511.  
  4512.  
  4513.  
  4514.  
  4515.  
  4516.  
  4517.  
  4518.  
  4519.  
  4520.  
  4521.  
  4522.  
  4523.  
  4524.  
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.  
  4531.  
  4532.  
  4533.  
  4534.  
  4535.  
  4536.  
  4537.  
  4538.  
  4539.  
  4540.  
  4541.  
  4542.  
  4543.  
  4544.  
  4545.  
  4546.  
  4547.  
  4548.        
  4549.        ======================================================================
  4550.        GemFast v1.8                                                   Page 64
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.        void gra_qmstate(short *px, short *py, short *pb)
  4560.        ______________________________________________________________________
  4561.  
  4562.        NOTE:     This old function is being phased out.  It used Line-A to
  4563.                  get the mouse state, and Atari has announced the death of
  4564.                  Line-A.  Use the standard graf_mkstate() function.
  4565.  
  4566.                  Your existing code will not break, but the new support for
  4567.                  this function just calls graf_mkstate(), so you might as
  4568.                  well convert your code.
  4569.  
  4570.        Source:   aesxbind\gramouse.c
  4571.  
  4572.  
  4573.  
  4574.  
  4575.        void gra_qofmouse(void)
  4576.        ______________________________________________________________________
  4577.  
  4578.        NOTE:     This old function is being phased out.  It used Line-A to
  4579.                  hide the mouse, and Atari has announced the death of Line-A. 
  4580.                  Use the standard graf_mouse() function.
  4581.  
  4582.                  Your existing code will not break, but the new support for
  4583.                  this function just calls graf_mouse(), so you might as well
  4584.                  convert your code.
  4585.  
  4586.        Source:   aesxbind\gramouse.c
  4587.  
  4588.  
  4589.  
  4590.        void gra_qonmouse(void)
  4591.        ______________________________________________________________________
  4592.  
  4593.        NOTE:     This old function is being phased out.  It used Line-A to
  4594.                  show the mouse, and Atari has announced the death of Line-A. 
  4595.                  Use the standard graf_mouse() function.
  4596.  
  4597.                  Your existing code will not break, but the new support for
  4598.                  this function just calls graf_mouse(), so you might as well
  4599.                  convert your code.
  4600.  
  4601.        Source:   aesxbind\gramouse.c
  4602.  
  4603.  
  4604.  
  4605.  
  4606.  
  4607.  
  4608.  
  4609.  
  4610.  
  4611.  
  4612.  
  4613.  
  4614.        
  4615.        ======================================================================
  4616.        GemFast v1.8                                                   Page 65
  4617.  
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.  
  4625.        long grf_blit(short options, void *pbuffer, void *prect)
  4626.        ______________________________________________________________________
  4627.  
  4628.        Summary:  Blits a rectangle between the screen and a memory buffer.
  4629.  
  4630.        Input:    The options parameter specifies options as a bitmap.  One of
  4631.                  the following must be specified:
  4632.         
  4633.                    GRF_BFROMSCREEN - Blit from screen to memory.
  4634.                    GRF_BTOSCREEN   - Blit from memory to screen.
  4635.                    GRF_BMEMCALC    - Do not blit, just calculate and return
  4636.                                      the amount of memory required.
  4637.  
  4638.                  In addition, the following may be ORed in with the above:
  4639.  
  4640.                    GRF_BOBJTREE    - The prect parameter is a pointer to an
  4641.                                      object tree, instead of a GRECT.
  4642.  
  4643.                  The pbuffer parameter is a pointer to the memory buffer for
  4644.                  the blit.  If the GRF_BMEMCALC flag is specified, this may
  4645.                  be NULL, otherwise it must not be NULL.
  4646.  
  4647.                  The prect parameter is normally a pointer to a GRECT that
  4648.                  describes the screen area to blit.  If the GRF_BOBJTREE flag
  4649.                  is specified, it is a pointer to an object tree, and the
  4650.                  rectangle the dialog occupies on-screen is used.
  4651.  
  4652.        Returns:  The amount of memory needed to do the blit.  If this value
  4653.                  is zero, no portion of the blit intersects the physical
  4654.                  screen.  (IE, the blit is completely clipped.)
  4655.  
  4656.        See Also: grf_memblit()
  4657.  
  4658.        Details:  This function simplifies the process of using blits to save
  4659.                  and restore portions of the screen.
  4660.  
  4661.                  If you specify the GRF_BOBJTREE flag, the prect pointer is
  4662.                  interpreted as a pointer to an object tree instead of a
  4663.                  pointer to a GRECT.  In this case, the screen rectangle is
  4664.                  obtained using frm_sizes(prect,...), so that the object
  4665.                  tree's screen location is the blit area.
  4666.  
  4667.                  If you specify the GRF_BMEMCALC flag, this function
  4668.                  calculates and returns the size needed for a memory buffer
  4669.                  to do this blit, but it does not actually blit anything.  
  4670.  
  4671.                  This function copies the prect rectangle to a work area and
  4672.                  does an rc_intersect(&gl_rfscrn, &workrect) to clip the blit
  4673.                  to the physical screen.  (VDI tends to hang the machine if
  4674.                  you try to do off-screen blits.)  If no portion of the
  4675.                  rectangle is on-screen, no blit is done, and zero is
  4676.                  returned.  Your prect rectangle can have negative x/y
  4677.                  values, but it must not have negative width or height.
  4678.  
  4679.  
  4680.        
  4681.        ======================================================================
  4682.        GemFast v1.8                                                   Page 66
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.                  The memory buffer is assumed to be the right size for the
  4692.                  blit.  The blit origin in the buffer is always 0,0.  In
  4693.                  other words, you can't allocate a single buffer and store
  4694.                  several discontiguous pieces of the screen into it, you must
  4695.                  allocate a separate buffer for each piece of the screen you
  4696.                  want to save simultaneously.  It is your responsibility to
  4697.                  use a buffer that is big enough to hold the contents of the
  4698.                  specified screen rectangle.  (Using a buffer bigger than
  4699.                  necessary doesn't hurt.)
  4700.  
  4701.                  This function uses the VDI shared workstation.  The mouse is
  4702.                  automatically hidden during the blit.
  4703.  
  4704.        Source:   aesfuncs\grfblit.c
  4705.  
  4706.  
  4707.  
  4708.  
  4709.  
  4710.  
  4711.  
  4712.  
  4713.  
  4714.  
  4715.  
  4716.  
  4717.  
  4718.  
  4719.  
  4720.  
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.        
  4747.        ======================================================================
  4748.        GemFast v1.8                                                   Page 67
  4749.  
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.  
  4757.        void * grf_memblit(short options, void *pbuffer, void *prect)
  4758.        ______________________________________________________________________
  4759.  
  4760.        Summary:  Allocates a buffer and blits a screen area into it, or
  4761.                  restores the screen and frees the buffer.
  4762.  
  4763.        Input:    The options parameter specifies options as a bitmap.  The
  4764.                  following options are available:
  4765.  
  4766.                    GRF_NORMAL      - The prect parameter is a pointer to a
  4767.                                      GRECT.
  4768.  
  4769.                    GRF_BOBJTREE    - The prect parameter is a pointer to an
  4770.                                      object tree, instead of a GRECT.
  4771.  
  4772.                  The pbuffer parameter both indicates blit direction and
  4773.                  specifies the buffer to use on a restore.
  4774.  
  4775.                  The prect parameter is a normally pointer to a GRECT that
  4776.                  describes the screen area to blit.  If the GRF_BOBJTREE flag
  4777.                  is specified, it is a pointer to an object tree, and the
  4778.                  rectangle the dialog occupies on-screen is used.
  4779.  
  4780.        Returns:  A pointer to the allocated buffer.  A NULL return value
  4781.                  indicates that a buffer could not be allocated, or the blit
  4782.                  area did not intersect the physical screen.
  4783.  
  4784.        See Also: grf_blit()
  4785.  
  4786.        Details:  This function provides the easiest way to save and restore
  4787.                  an area of the screen.
  4788.  
  4789.                  When you pass a NULL buffer pointer, this function allocates
  4790.                  a buffer (of just the right size), and saves the specified
  4791.                  screen rectangle into it.  It returns a pointer to the
  4792.                  allocated buffer.
  4793.  
  4794.                  To restore that screen area, call this function again,
  4795.                  passing the pointer it returned to you when you saved the
  4796.                  screen area.  It restores the screen and deallocates the
  4797.                  buffer.  (The return value in this case is garbage.)
  4798.  
  4799.                  When saving a screen area, be sure to check the returned
  4800.                  pointer to ensure the blit worked.
  4801.  
  4802.                  Any number of screen areas can be saved simultaneously with
  4803.                  multiple calls to this function, since the buffers are
  4804.                  dynamically allocated.
  4805.  
  4806.                  The mouse is automatically hidden during the blit.
  4807.  
  4808.        Source:   aesfuncs\grfmblit.c
  4809.  
  4810.  
  4811.  
  4812.        
  4813.        ======================================================================
  4814.        GemFast v1.8                                                   Page 68
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.        short graf_mouse(short shape, void *pform)
  4824.        short grf_mouse(short shape, void *pform)
  4825.        ______________________________________________________________________
  4826.  
  4827.        Summary:  Inquire, alter, or restore the mouse cursor shape.
  4828.  
  4829.        NOTE:     A macro in GEMFAST.H remaps graf_mouse to grf_mouse so that
  4830.                  your existing code need not be changed.
  4831.  
  4832.        Input:    The shape parameter specifies the action of this function. 
  4833.                  It can have any of the standard GEM-defined values (ARROW,
  4834.                  BUSYBEE, M_ON, etc).  In addition, there is one special
  4835.                  action available:
  4836.  
  4837.                    GRF_MSINQUIRE -   Return information about the current
  4838.                                      mouse shape; do not change the mouse.
  4839.  
  4840.                  The pform parameter is interpreted differently depending on
  4841.                  the value of the shape parameter; details below.
  4842.  
  4843.        Returns:  The shape the cursor was set to before the call, or 0 if an
  4844.                  error occurred.  When the prior shape was ARROW, it is
  4845.                  handled specially; details below.
  4846.  
  4847.        See Also:
  4848.  
  4849.        Details:  GEM doesn't provide a way to inquire what the current mouse
  4850.                  shape is, so this function does it for you.  It keeps track
  4851.                  of the current mouse shape in static variables so that it
  4852.                  can return the value to you.  Naturally, this only works if
  4853.                  all changes to the mouse shape are made through this
  4854.                  routine, so a macro in GEMFAST.H remaps your existing
  4855.                  graf_mouse() calls through this function.
  4856.  
  4857.                  The GEM graf_mouse() function returns zero/non-zero, and
  4858.                  this function is compatible with that.  But, when this
  4859.                  function returns a non-zero value (indicating success), that
  4860.                  value is the shape of the mouse before call.  You can use
  4861.                  this to temporarily change the mouse shape then restore it:
  4862.  
  4863.                      old_shape = graf_mouse(ARROW, NULL);
  4864.                      /* do something */
  4865.                      graf_mouse(old_shape, NULL);
  4866.  
  4867.                  If the old shape was ARROW (0), this function can't return
  4868.                  ARROW, because that would look like a failure of the call. 
  4869.                  Instead, it returns the special value 200, defined as
  4870.                  GRF_MSALTARROW.  When you pass GRF_MSALTARROW as the shape
  4871.                  parameter to this function, it is automatically translated
  4872.                  back to ARROW before being passed along to GEM in the real
  4873.                  graf_mouse() call.
  4874.  
  4875.                  If you pass the special value GRF_MSINQUIRE as the shape
  4876.                  parameter to this function, it returns information about the
  4877.  
  4878.        
  4879.        ======================================================================
  4880.        GemFast v1.8                                                   Page 69
  4881.  
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.                  current mouse shape without changing it.  In this case, the
  4890.                  pform parameter is interpreted differently.  If pform is
  4891.                  NULL, this function just returns the current shape number
  4892.                  without changing the shape.  If you pass a non-NULL pform
  4893.                  with GRF_MSINQUIRE, it is a pointer to a pointer variable
  4894.                  into which the current user-defined form pointer is stored. 
  4895.                  This feature is used as follows:
  4896.          
  4897.                      void *oldform;
  4898.                      short  oldshape;
  4899.  
  4900.                      oldshape = graf_mouse(GRF_MSINQUIRE, &oldform);
  4901.                      graf_mouse(USER_DEF, myform);
  4902.                      /* do something with your custom mouse form */
  4903.                      graf_mouse(oldshape, oldform);
  4904.  
  4905.                  You only need to use this technique if you are going to
  4906.                  change the shape to your own user-defined shape.  If the
  4907.                  mouse was a user-defined shape, and you change it to a
  4908.                  standard system shape, then graf_mouse(oldshape, NULL) will
  4909.                  restore the prior user-defined shape properly.
  4910.  
  4911.        Source:   aesfuncs\grfmouse.c
  4912.  
  4913.  
  4914.  
  4915.  
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.  
  4942.  
  4943.  
  4944.        
  4945.        ======================================================================
  4946.        GemFast v1.8                                                   Page 70
  4947.  
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.  
  4955.        Menu Library
  4956.  
  4957.  
  4958.                  The menu library contains functions which help you manage
  4959.                  the GEM menu bar.  It contains several functions that exist
  4960.                  primarily to support GemFast internals, and several things
  4961.                  which provide functionality GEM doesn't give you directly.
  4962.  
  4963.                  Use of any of these functions other than menu_bar() might
  4964.                  make your program incompatible with MultiTOS.  I don't know
  4965.                  this for sure, if someone can verify it, please tell me.
  4966.  
  4967.  
  4968.  
  4969.  
  4970.  
  4971.  
  4972.  
  4973.  
  4974.  
  4975.  
  4976.  
  4977.  
  4978.  
  4979.  
  4980.  
  4981.  
  4982.  
  4983.  
  4984.  
  4985.  
  4986.  
  4987.  
  4988.  
  4989.  
  4990.  
  4991.  
  4992.  
  4993.  
  4994.  
  4995.  
  4996.  
  4997.  
  4998.  
  4999.  
  5000.  
  5001.  
  5002.  
  5003.  
  5004.  
  5005.  
  5006.  
  5007.  
  5008.  
  5009.  
  5010.        
  5011.        ======================================================================
  5012.        GemFast v1.8                                                   Page 71
  5013.  
  5014.  
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020.  
  5021.        short menu_bar(OBJECT *ptree, short on_off_flag)
  5022.        short mnu_bar(OBJECT *ptree, short on_off_flag, long reserved)
  5023.        ______________________________________________________________________
  5024.  
  5025.        Summary:  Turn the menu bar on or off in a way that it can
  5026.                  transparently enabled and disabled.
  5027.  
  5028.        NOTE:     A macro in GEMFAST.H remaps menu_bar to mnu_bar so that your
  5029.                  existing code need not be changed.
  5030.  
  5031.        Input:    The ptree parameter is a pointer to the object tree
  5032.                  describing the menu.
  5033.  
  5034.                  The on_off_flag parameter indicates whether you are turning
  5035.                  the specified menu on (ie, installing it), or turning it off
  5036.                  (removing it).
  5037.  
  5038.                  The reserved parameter is for future use, and must be zero. 
  5039.                  (The menu_bar() macro supplies the zero.)
  5040.  
  5041.        Returns:  Zero for failure or non-zero for success.
  5042.  
  5043.        See Also: mnu_enable() mnu_disable()
  5044.  
  5045.        Details:  This function helps implement menus that can be temporarily
  5046.                  disabled.  There are times when a library routine wants to
  5047.                  disable menu processing without disabling window controls as
  5048.                  well (in other words, wind_update() is sometimes too
  5049.                  strong).  GEM's menu_bar(whatever,0) function can disable
  5050.                  the menu, but then you have to have the pointer to the menu
  5051.                  tree available to re-enable it.
  5052.  
  5053.                  This function simply remembers the menu tree pointer when
  5054.                  the application turns on its menu.  This allows the related
  5055.                  mnu_enable() and mnu_disable() functions to make menu_bar()
  5056.                  calls to turn the menu on and off using whatever menu tree
  5057.                  was last supplied by the application.
  5058.  
  5059.                  This works because menu_bar(whatever, 0) disables menu
  5060.                  processing, but does not actually erase the menu from the
  5061.                  screen.  If GEM's menu_bar() ever starts erasing the menu
  5062.                  visually, I'm going to have a lot of kludging to do.
  5063.  
  5064.        Source:   aesfuncs\mnubar.c
  5065.  
  5066.  
  5067.  
  5068.  
  5069.  
  5070.  
  5071.  
  5072.  
  5073.  
  5074.  
  5075.  
  5076.        
  5077.        ======================================================================
  5078.        GemFast v1.8                                                   Page 72
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.  
  5087.        void mnu_disable(void)
  5088.        ______________________________________________________________________
  5089.  
  5090.        Summary:  Disable the menu bar from responding to the mouse.
  5091.  
  5092.        Input:    Nothing.
  5093.  
  5094.        Returns:  Nothing.
  5095.  
  5096.        See Also: mnu_enable() mnu_bar()
  5097.  
  5098.        Details:  This function prevents the menu bar from responding to the
  5099.                  mouse, but it does not also disable window controls like
  5100.                  wind_update() does.  It works like hide/show mouse calls, in
  5101.                  that 3 calls to mnu_disable() will require 3 calls to
  5102.                  mnu_enable() to get the menus active again.
  5103.  
  5104.        Source:   aesfuncs\mnubar.c
  5105.  
  5106.  
  5107.  
  5108.  
  5109.  
  5110.  
  5111.  
  5112.  
  5113.  
  5114.  
  5115.  
  5116.  
  5117.  
  5118.  
  5119.  
  5120.  
  5121.  
  5122.  
  5123.  
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  
  5131.  
  5132.  
  5133.  
  5134.  
  5135.  
  5136.  
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.        
  5143.        ======================================================================
  5144.        GemFast v1.8                                                   Page 73
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.        void mnu_enable(void)
  5154.        ______________________________________________________________________
  5155.  
  5156.        Summary:  Re-enable the menu bar to respond to the mouse.
  5157.  
  5158.        Input:    Nothing.
  5159.  
  5160.        Returns:  Nothing.
  5161.  
  5162.        See Also: mnu_disable() mnu_bar()
  5163.  
  5164.        Details:  This function allows the menu bar to begin responding to
  5165.                  mouse events again after it had been disabled.  It works
  5166.                  like hide/show mouse calls, in that 3 calls to mnu_disable()
  5167.                  will require 3 calls to mnu_enable() to get the menus active
  5168.                  again.
  5169.  
  5170.        Source:   aesfuncs\mnubar.c
  5171.  
  5172.  
  5173.  
  5174.  
  5175.  
  5176.  
  5177.  
  5178.  
  5179.  
  5180.  
  5181.  
  5182.  
  5183.  
  5184.  
  5185.  
  5186.  
  5187.  
  5188.  
  5189.  
  5190.  
  5191.  
  5192.  
  5193.  
  5194.  
  5195.  
  5196.  
  5197.  
  5198.  
  5199.  
  5200.  
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.        
  5209.        ======================================================================
  5210.        GemFast v1.8                                                   Page 74
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.        void mnu_erase(void)
  5220.        ______________________________________________________________________
  5221.  
  5222.        Summary:  Turn of the menu bar and remove it from the screen.
  5223.  
  5224.        Input:    Nothing.
  5225.  
  5226.        Returns:  Nothing.
  5227.  
  5228.        See Also: mnu_tbar()
  5229.  
  5230.        Details:  This function turns off the current menu (if any), and
  5231.                  erases the menu bar area of the screen.
  5232.  
  5233.        Source:   aesfuncs\mnutbar.c
  5234.  
  5235.  
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.  
  5247.  
  5248.  
  5249.  
  5250.  
  5251.  
  5252.  
  5253.  
  5254.  
  5255.  
  5256.  
  5257.  
  5258.  
  5259.  
  5260.  
  5261.  
  5262.  
  5263.  
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.        
  5275.        ======================================================================
  5276.        GemFast v1.8                                                   Page 75
  5277.  
  5278.  
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.  
  5285.        void mnu_tbar(char *title)
  5286.        ______________________________________________________________________
  5287.  
  5288.        Summary:  Turn of the menu bar and display a text string in its place.
  5289.  
  5290.        Input:    The title parameter is a pointer to the string to be
  5291.                  displayed in the menu bar.
  5292.  
  5293.        Returns:  Nothing.
  5294.  
  5295.        See Also: mnu_erase()
  5296.  
  5297.        Details:  This function turns off the current menu (if any), and
  5298.                  displays the specified string centered in the menu bar area
  5299.                  of the screen.  
  5300.  
  5301.        Example:  If your program allows the user to "shell out" to other
  5302.                  programs, you can use this function to display the name of
  5303.                  the program before executing it, like the GEM desktop does:
  5304.  
  5305.                  void exec_a_program(char *fname)
  5306.                  {
  5307.                      static char fullpath[128];
  5308.                      strcpy(fullpath, fname);
  5309.                      if (!shel_find(fullpath)) 
  5310.                          return frm_qerror(-33, "Can't exec program");
  5311.                      graf_mouse(BEE, NULL);      // make mouse a BEE, and put
  5312.                      mnu_tbar(fullpath);         // program name in menu bar.
  5313.                      Pexec(0, fullpath, "\0", NULL);
  5314.                      menu_bar(my_normal_menu,1); // restore our menu bar, and
  5315.                      graf_mouse(ARROW, NULL);    // make sure mouse is ARROW.
  5316.                      return Success;
  5317.                  }
  5318.  
  5319.        Source:   aesfuncs\mnutbar.c
  5320.  
  5321.  
  5322.  
  5323.  
  5324.  
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.  
  5335.  
  5336.  
  5337.  
  5338.  
  5339.  
  5340.        
  5341.        ======================================================================
  5342.        GemFast v1.8                                                   Page 76
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.  
  5351.        Object Library
  5352.  
  5353.  
  5354.                  The object library contains functions which manipulate an
  5355.                  object in a tree.  There are functions for getting and
  5356.                  setting most of the common object structure fields.
  5357.  
  5358.                  Directly accessing the fields in an object, especially the
  5359.                  ob_spec field, is becoming an increasingly dangerous thing
  5360.                  to do when using GemFast.  The extended object library now
  5361.                  implements a variety of new objects, or modifies the
  5362.                  behavior or existing objects, and this is largely done by
  5363.                  'hooking' the objects through their ob_type and ob_spec
  5364.                  fields.  (The high byte of ob_type, the so-called 'extended
  5365.                  object type field' is never touched by GemFast internals,
  5366.                  but the low byte is often changed to a G_USERDEF type, and
  5367.                  the original type is moved into the XUSERDEF block attached
  5368.                  to the object via its ob_spec field.)  
  5369.  
  5370.                  Note that GemFast never modifies objects other than when you
  5371.                  specifically direct it to, by calling one of the functions
  5372.                  that transforms an existing object into an extended object. 
  5373.                  Still, inasmuch as you may decide at a later date to
  5374.                  transform an object, it is safest to use the access
  5375.                  functions to get at ob_type and ob_spec values.
  5376.  
  5377.                  GemFast internals never modify an object's INDIRECT flag;
  5378.                  that is left as a method for an application to 'hook' the
  5379.                  object.  All GemFast internals do correctly handle objects
  5380.                  with the INDIRECT flag set, so you may use the INDIRECT flag
  5381.                  yourself to tie your own extra data to an object.
  5382.  
  5383.                  Because the value associated with an object may be
  5384.                  indirected through a G_USERDEF and/or INDIRECT flag, it is
  5385.                  best to use the object library functions to access the
  5386.                  values associated with an object.  These values can be
  5387.                  strings, numbers, or pointers to GemFast-defined structures. 
  5388.                  The following functions are provided as a safe way to
  5389.                  manipulate an object's associated values:
  5390.  
  5391.                      obj_gstring()  -    Get object's string pointer.
  5392.                      obj_sstring()  -    Set object's string pointer.
  5393.                      obj_gvalue()   -    Get object's numeric value.
  5394.                      obj_svalue()   -    Set object's numeric value.
  5395.                      obj_gtype()    -    Get object's basic ob_type.
  5396.  
  5397.                  Several functions which used to be in the object library
  5398.                  have been moved to the extended object library, and now have
  5399.                  an xob_ prefix.  These functions are still accepted via
  5400.                  their former obj_ names as well.  The functions are:
  5401.  
  5402.                      obj_mkthermo    ->  xob_thermo_create
  5403.                      obj_udthermo    ->  xob_thermo_update
  5404.                      obj_mxuserdef   ->  xob_transform
  5405.  
  5406.        
  5407.        ======================================================================
  5408.        GemFast v1.8                                                   Page 77
  5409.  
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  
  5416.  
  5417.        short obj_bmbuttons(OBJECT *ptree, short parent, short select_state,
  5418.                            short newbits)
  5419.        ______________________________________________________________________
  5420.  
  5421.        Summary:  Translate a group of buttons with extended type info into a
  5422.                  bitmap-vector or vice versa.
  5423.  
  5424.        Input:    The ptree parameter is a pointer to the tree containing the
  5425.                  button group.
  5426.  
  5427.                  The parent parameter is the index of the object which is the
  5428.                  direct parent of the group of buttons.
  5429.  
  5430.                  The select_state parameter is a mask of ob_state bits used
  5431.                  to select an object.
  5432.  
  5433.                  The newbits parameter contains the bitmap to be translated
  5434.                  into selected buttons, or it contains the special value
  5435.                  OBJ_BMINQUIRE which indicates that you want to get the
  5436.                  bitmap describing the selected buttons without changing the
  5437.                  button states.
  5438.  
  5439.        Returns:  A bitmap of the buttons that were selected before the call.
  5440.  
  5441.        See also: rsc_sxtypes() obj_xtfind()
  5442.  
  5443.        Details:  This function is useful when you have a group of buttons in
  5444.                  a dialog which represent on/off options that your program
  5445.                  can handle.  When your program supports a variety of
  5446.                  options, a common technique is to use bits within a word to
  5447.                  represent the options.  (Like the options in the GemFast
  5448.                  forms library.)  This function helps you translate the state
  5449.                  of the dialog buttons to and from the bitmapped
  5450.                  representation used within your program.
  5451.  
  5452.                  The extended object type field is the upper 8 bits of the
  5453.                  ob_type field in an object.  These bits are always available
  5454.                  to your program for any use you want.  By setting the
  5455.                  extended object types for a collection of buttons to the
  5456.                  values representing your bitmapped options, you can easily
  5457.                  relate each button to the option it represents within your
  5458.                  program.  Up to 8 options can be encoded in a group of
  5459.                  buttons in this way.  If you need more than 8 options, just
  5460.                  use more than one parent object, and put 8 buttons in each
  5461.                  parent.  (The parent can be an IBOX so that the user doesn't
  5462.                  know you've performed any arbitrary grouping.)  Some
  5463.                  resource editors let you specify the extended object type
  5464.                  when you define your dialog.  If yours doesn't, just use the
  5465.                  rsc_sxtypes() function during program startup.
  5466.  
  5467.                  When you pass a newbits value of OBJ_BMINQUIRE, this
  5468.                  function checks each object within the parent.  It ANDs each
  5469.                  object's ob_state field with the select_state parameter, and
  5470.                  if the result is non-zero, it ORs the object's extended
  5471.  
  5472.        
  5473.        ======================================================================
  5474.        GemFast v1.8                                                   Page 78
  5475.  
  5476.  
  5477.  
  5478.  
  5479.  
  5480.  
  5481.  
  5482.  
  5483.                  object type into the return value.  The return value is the
  5484.                  bitmap of all extended type values for objects that were in
  5485.                  a selected state.
  5486.  
  5487.                  When you pass any value other than OBJ_BMINQUIRE for the
  5488.                  newbits parameter, this function changes the state of the
  5489.                  objects as well as returning the old-state bitmap.  In this
  5490.                  case, it again checks each object within the parent, but it
  5491.                  ANDs the newbits with the extended object type of each
  5492.                  object.  When the result is non-zero, it ORs the
  5493.                  select_state value into the object's ob_state; when the
  5494.                  result is zero, it ANDs ~select_state with the object's
  5495.                  ob_state.  This results in selecting all buttons which
  5496.                  represent 1 bits in the newbits parameter, and deselecting
  5497.                  all buttons which represent 0 bits in newbits.
  5498.  
  5499.                  Note that the objects don't have to be buttons; this
  5500.                  function keys off of the extended object type and state
  5501.                  fields only.
  5502.  
  5503.        Example:  Suppose your program has four options, and a dialog box that
  5504.                  lets users turn each of those options on or off with
  5505.                  selection (ie, non-radio) buttons.  The following code
  5506.  
  5507.  
  5508.  
  5509.  
  5510.  
  5511.  
  5512.  
  5513.  
  5514.  
  5515.  
  5516.  
  5517.  
  5518.  
  5519.  
  5520.  
  5521.  
  5522.  
  5523.  
  5524.  
  5525.  
  5526.  
  5527.  
  5528.  
  5529.  
  5530.  
  5531.  
  5532.  
  5533.  
  5534.  
  5535.  
  5536.  
  5537.  
  5538.        
  5539.        ======================================================================
  5540.        GemFast v1.8                                                   Page 79
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.                  fragments illustrate how this function helps:
  5550.  
  5551.                      #define AUTOSAVE    0x0001
  5552.                      #define AUTOBACKUP  0x0002
  5553.                      #define FILEOUTPUT  0x0004
  5554.                      #define PRINTOUTPUT 0x0008
  5555.  
  5556.                      short options = AUTOSAVE | FILEOUTPUT; // defaults
  5557.  
  5558.                      OBJECT *option_dialog;
  5559.  
  5560.                      void prog_init()
  5561.                      {
  5562.                          appl_init();
  5563.                          rsrc_load(etc, etc);
  5564.                          rsc_gtrees(OPTIONDIALOG, &option_dialog, -1);
  5565.  
  5566.                          /*
  5567.                           * set button extended types to our bit values...
  5568.                           */
  5569.  
  5570.                          rsc_sxtypes(option_dialog,
  5571.                              AUTOSAVE_BUTTON, AUTOSAVE,
  5572.                              AUTOBACK_BUTTON, AUTOBACKUP,
  5573.                              FILEOUT_BUTTON,  FILEOUTPUT,
  5574.                              PRTOUT_BUTTON,   PRINTFOUTPUT,
  5575.                              -1);
  5576.                      }
  5577.  
  5578.                      void do_options_dialog()
  5579.                      {
  5580.                          /*
  5581.                           * translate current options to selected buttons...
  5582.                           */
  5583.  
  5584.                          obj_bmbuttons(option_dialog, 
  5585.                              BUTTON_PARENT, SELECTED, options);
  5586.  
  5587.                          /* 
  5588.                           * do dialog...
  5589.                           */
  5590.  
  5591.                          frm_dialog(FRM_CENTER, option_dialog, 0);
  5592.  
  5593.                          /*
  5594.                           * translate buttons now selected back into options
  5595.                           * variable...
  5596.                           */
  5597.  
  5598.                          options = obj_bmbuttons(option_dialog,
  5599.                              BUTTON_PARENT, SELECTED, OBJ_BMINQUIRE);
  5600.                      }
  5601.  
  5602.        Source:   aesfuncs\objbmbtn.c
  5603.  
  5604.        
  5605.        ======================================================================
  5606.        GemFast v1.8                                                   Page 80
  5607.  
  5608.  
  5609.  
  5610.  
  5611.  
  5612.  
  5613.  
  5614.  
  5615.        short obj_clcalc(OBJECT *ptree, short object, GRECT *pgrect,
  5616.                         VRECT *pvrect)
  5617.        ______________________________________________________________________
  5618.  
  5619.        Summary:  Calculates a clipping rectangle for an object.
  5620.  
  5621.        Input:    The ptree parameter is a pointer to the tree containing the
  5622.                  object.
  5623.  
  5624.                  The object parameter is the index of the object to be
  5625.                  calculated.
  5626.  
  5627.                  The pgrect parameter is a pointer to a GRECT structure into
  5628.                  which the results are returned.  If this is NULL, the
  5629.                  results are not returned in GRECT format.
  5630.  
  5631.                  The pvrect parameter is a pointer to a VRECT structure into
  5632.                  which the results are returned.  If this is NULL, the
  5633.                  results are not returned in VRECT format.
  5634.  
  5635.        Returns:  The adjustment applied to the object's basic rectangle to
  5636.                  arrive at the on-screen rectangle.  Always zero or greater. 
  5637.                  (EG, a value of 4 indicates that the returned rectangle is 4
  5638.                  pixels larger on all sides than the rectangle described by
  5639.                  the object's xywh values.)
  5640.  
  5641.        See Also: frm_sizes()
  5642.  
  5643.        Details:  This function calculates the rectangle that an object
  5644.                  occupies on the screen.  It understands that some objects
  5645.                  have an on-screen size larger than their xywh values imply. 
  5646.                  (IE, when the object is OUTLINED, SHADOWED, etc).
  5647.  
  5648.                  If you want to calculate the rectangle for an entire tree,
  5649.                  the frm_sizes() function is easier to code.
  5650.  
  5651.                  Do not count on this function for absolute precision.  The
  5652.                  calculated rectangle will fully enclose the object, but it
  5653.                  might be a pixel or two larger than the visual boundary of
  5654.                  the object.  (This is because of the arcane rules for
  5655.                  SHADOWED objects in particular.)  So this function will
  5656.                  always work if you want to save the screen under the object;
  5657.                  you may just save a couple pixels more than you need to. 
  5658.                  But, it may not be sufficient if you want to accurately
  5659.                  outline the object with a box drawn via VDI calls, for
  5660.                  example.
  5661.  
  5662.                  Prior GemFast docs stated that this function was obsolete
  5663.                  and was being phased out.  Instead of obsoleting it, I threw
  5664.                  away the buggy old assembler code and rewrote it in C.  I
  5665.                  don't plan to phase it out anymore.
  5666.  
  5667.        Source:   aesfuncs\objclcal.c
  5668.  
  5669.  
  5670.        
  5671.        ======================================================================
  5672.        GemFast v1.8                                                   Page 81
  5673.  
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.  
  5681.        void obj_flchange(OBJECT *ptree, short object, short newflags,
  5682.                          short drawflag [ ,GRECT *cliprect ])
  5683.        ______________________________________________________________________
  5684.  
  5685.        Summary:  Change an object's flags, with optional redraw.
  5686.  
  5687.        Input:    The ptree parameter is a pointer to the tree containing the
  5688.                  object to change.
  5689.  
  5690.                  The object parameter is the index of the object to change.
  5691.  
  5692.                  The newflags parameter specifies which object flag bits to
  5693.                  change; details below.  
  5694.  
  5695.                  The drawflag parameter specifies whether the object is to be
  5696.                  visually updated on the screen, use one of the following:
  5697.  
  5698.                    OBJ_NODRAW   (0) -    Don't update the screen.
  5699.                    OBJ_WITHDRAW (1) -    Update the screen.
  5700.                    OBJ_CLIPDRAW (2) -    Update the screen with clipping.
  5701.  
  5702.                  The cliprect parameter is an optional pointer to a rectangle
  5703.                  which will be used to clip the redraw of the object.  This
  5704.                  parameter is only used when the drawflag parameter is equal
  5705.                  to OBJ_CLIPDRAW.
  5706.  
  5707.        Returns:  Nothing.
  5708.  
  5709.        See Also:
  5710.  
  5711.        Details:  This function provides a simple way to change the object
  5712.                  flag bits for any object.
  5713.  
  5714.                  If the high bit of the newflags parameter is set, an AND is
  5715.                  used to mask off bits in the object flags.  If the high bit
  5716.                  is not set, an OR is used to set bits in the object flags. 
  5717.                  This allows a newflags value of DEFAULT to set the default
  5718.                  bit, and a value of ~DEFAULT to unset it.
  5719.  
  5720.                  When the drawflag parameter is non-zero, an objc_draw() call
  5721.                  is automatically done after the flags are changed.  The
  5722.                  objc_draw() is always done starting at the root object and
  5723.                  drawing to MAX_DEPTH, and the draw is clipped to the on-
  5724.                  screen rectangle of the object being changed.  This allows a
  5725.                  change that sets HIDETREE to properly hide the object
  5726.                  visually, because the parent of the object is redrawn, but
  5727.                  the object itself is not.
  5728.  
  5729.                  When your dialog is in a window and you need to clip the
  5730.                  redraw, use the OBJ_CLIPDRAW option, and provide a pointer
  5731.                  to the clipping rectangle.  If the draw option is not
  5732.                  CLIPDRAW, the clip pointer need not be specified.
  5733.  
  5734.        Source:   aesfuncs\objflchg.c
  5735.  
  5736.        
  5737.        ======================================================================
  5738.        GemFast v1.8                                                   Page 82
  5739.  
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.  
  5747.        char * obj_gstring(OBJECT *ptree, short object)
  5748.        ______________________________________________________________________
  5749.  
  5750.        Summary:  Obtain an object's string pointer.
  5751.  
  5752.        Input:    The ptree parameter is a pointer to the tree containing the
  5753.                  object.
  5754.  
  5755.                  The object parameter is the index of the object.
  5756.  
  5757.        Returns:  Pointer to object's associated string.
  5758.  
  5759.        See Also: rsc_sstrings() obj_sstring() obj_gvalue() obj_svalue()
  5760.  
  5761.        Details:  This function gets a string pointer which is associated with
  5762.                  a string-related object.  
  5763.  
  5764.                  In standard GEM programming, an object's ob_spec field
  5765.                  points to the string.  In GemFast, however, an increasing
  5766.                  number of extended objects have their string pointers stored
  5767.                  in an extension block, and the object's ob_spec points at
  5768.                  the extension block. 
  5769.  
  5770.                  This function understands how to find the real string
  5771.                  pointer for all string-related object types.  It copes with
  5772.                  the INDIRECT flag.  It understands extended G_USERDEF
  5773.                  objects, where ob_spec has been moved into the XUSERBLK.
  5774.  
  5775.                  When an object is not string-related, the obj_gvalue()
  5776.                  function should be used instead of this function.
  5777.  
  5778.        Source:   aesfuncs\objppstr.c
  5779.  
  5780.  
  5781.  
  5782.  
  5783.  
  5784.  
  5785.  
  5786.  
  5787.  
  5788.  
  5789.  
  5790.  
  5791.  
  5792.  
  5793.  
  5794.  
  5795.  
  5796.  
  5797.  
  5798.  
  5799.  
  5800.  
  5801.  
  5802.        
  5803.        ======================================================================
  5804.        GemFast v1.8                                                   Page 83
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.  
  5813.        short obj_gtype(OBJECT *ptree, short object)
  5814.        ______________________________________________________________________
  5815.  
  5816.        Summary:  Obtain an object's ob_type.
  5817.  
  5818.        Input:    The ptree parameter is a pointer to the tree containing the
  5819.                  object.
  5820.  
  5821.                  The object parameter is the index of the object.
  5822.  
  5823.        Returns:  The basic ob_type of the object.
  5824.  
  5825.        See Also:
  5826.  
  5827.        Details:  This function obtains an object's basic ob_type value.  If
  5828.                  the object has any extended object type in the high byte of
  5829.                  its ob_type field, that information is NOT returned.  (It is
  5830.                  always safe to access the extended object type stored in the
  5831.                  high byte of an object's ob_type field directly, since
  5832.                  GemFast internals never touch that byte.)
  5833.  
  5834.                  This function understands extended object types, where the
  5835.                  original ob_type is either GemFast-defined or has been moved
  5836.                  into the XUSERBLK structure attached to the object.  For
  5837.                  these types of objects, it returns the actual object type,
  5838.                  not the G_USERDEF type found by looking directly at the
  5839.                  ob_type field.
  5840.  
  5841.        Source:   aesfuncs\objgtype.c
  5842.  
  5843.  
  5844.  
  5845.  
  5846.  
  5847.  
  5848.  
  5849.  
  5850.  
  5851.  
  5852.  
  5853.  
  5854.  
  5855.  
  5856.  
  5857.  
  5858.  
  5859.  
  5860.  
  5861.  
  5862.  
  5863.  
  5864.  
  5865.  
  5866.  
  5867.  
  5868.        
  5869.        ======================================================================
  5870.        GemFast v1.8                                                   Page 84
  5871.  
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.  
  5879.        long obj_gvalue(OBJECT *ptree, short object)
  5880.        ______________________________________________________________________
  5881.  
  5882.        Summary:  Obtain an object's associated value.
  5883.  
  5884.        Input:    The ptree parameter is a pointer to the tree containing the
  5885.                  object.
  5886.  
  5887.                  The object parameter is the index of the object.
  5888.  
  5889.        Returns:  The value associated with the object.
  5890.  
  5891.        See Also: obj_svalue() obj_gstring() obj_sstring()
  5892.  
  5893.        Details:  This function obtains the value which is associated with an
  5894.                  object.
  5895.  
  5896.                  In standard GEM programming, an object's ob_spec field holds
  5897.                  the object's value, which is usually related to drawing the
  5898.                  value in some way.  In GemFast, however, a number of
  5899.                  extended objects have numeric values associated with them
  5900.                  which are stored in an extension block, and the object's
  5901.                  ob_spec points at the extension block. 
  5902.  
  5903.                  When an object is string-related, the obj_gstring() function
  5904.                  should be used instead of this function.
  5905.  
  5906.        Source:   aesfuncs\objgspec.c
  5907.  
  5908.  
  5909.  
  5910.  
  5911.  
  5912.  
  5913.  
  5914.  
  5915.  
  5916.  
  5917.  
  5918.  
  5919.  
  5920.  
  5921.  
  5922.  
  5923.  
  5924.  
  5925.  
  5926.  
  5927.  
  5928.  
  5929.  
  5930.  
  5931.  
  5932.  
  5933.  
  5934.        
  5935.        ======================================================================
  5936.        GemFast v1.8                                                   Page 85
  5937.  
  5938.  
  5939.  
  5940.  
  5941.  
  5942.  
  5943.  
  5944.  
  5945.        void obj_offxywh(OBJECT *ptree, short object, GRECT *prect)
  5946.        ______________________________________________________________________
  5947.  
  5948.        Summary:  Get the screen-adjusted xywh values for an object.
  5949.  
  5950.        Input:    The ptree parameter is a pointer to the object tree.
  5951.  
  5952.                  The object parameter is the index of the object.
  5953.  
  5954.                  The prect parameter is a pointer to the rectangle into which
  5955.                  the object's xywh values are returned.
  5956.  
  5957.        Returns:  Nothing.
  5958.  
  5959.        See Also: obj_clcalc()
  5960.  
  5961.        Details:  This function gets the screen-adjusted xywh values for the
  5962.                  object.  It does NOT take into account that some objects are
  5963.                  visually larger than their xywh values imply (ie, OUTLINED
  5964.                  objects).  Use the obj_clcalc() function if you need to
  5965.                  account for the actual visual area an object occupies on the
  5966.                  screen.
  5967.  
  5968.        Source:   aesfuncs\objoxywh.c
  5969.  
  5970.  
  5971.  
  5972.  
  5973.  
  5974.  
  5975.  
  5976.  
  5977.  
  5978.  
  5979.  
  5980.  
  5981.  
  5982.  
  5983.  
  5984.  
  5985.  
  5986.  
  5987.  
  5988.  
  5989.  
  5990.  
  5991.  
  5992.  
  5993.  
  5994.  
  5995.  
  5996.  
  5997.  
  5998.  
  5999.  
  6000.        
  6001.        ======================================================================
  6002.        GemFast v1.8                                                   Page 86
  6003.  
  6004.  
  6005.  
  6006.  
  6007.  
  6008.  
  6009.  
  6010.  
  6011.        short obj_parent(OBJECT *ptree, short object)
  6012.        ______________________________________________________________________
  6013.  
  6014.        Summary:  Return the parent object for the specified object.
  6015.  
  6016.        Input:    The ptree parameter is a pointer to the object tree.
  6017.  
  6018.                  The object parameter is the index of the object.
  6019.  
  6020.        Returns:  The index of the parent object.
  6021.  
  6022.        See Also:
  6023.  
  6024.        Details:  By definition, the root object has no parent.  If you try to
  6025.                  get the parent of the root, zero is returned, as if the root
  6026.                  were its own parent.
  6027.  
  6028.        Source:   aesfuncs\objrbutl.c
  6029.  
  6030.  
  6031.  
  6032.  
  6033.  
  6034.  
  6035.  
  6036.  
  6037.  
  6038.  
  6039.  
  6040.  
  6041.  
  6042.  
  6043.  
  6044.  
  6045.  
  6046.  
  6047.  
  6048.  
  6049.  
  6050.  
  6051.  
  6052.  
  6053.  
  6054.  
  6055.  
  6056.  
  6057.  
  6058.  
  6059.  
  6060.  
  6061.  
  6062.  
  6063.  
  6064.  
  6065.  
  6066.        
  6067.        ======================================================================
  6068.        GemFast v1.8                                                   Page 87
  6069.  
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.  
  6077.        char ** obj_ppstring(OBJECT *pobj)
  6078.        ______________________________________________________________________
  6079.  
  6080.        Summary:  Return a pointer to an object's string pointer.
  6081.  
  6082.        Input:    The pobj parameter is a pointer to the object.
  6083.  
  6084.        Returns:  A pointer to the object's string pointer.  Undefined if the
  6085.                  object isn't string-related.
  6086.  
  6087.        See Also: rsc_gstrings() rsc_sstrings() obj_gstring() obj_sstring()
  6088.  
  6089.        Details:  This routine exists primarily to support other library
  6090.                  routines, but you can use it directly.  It returns a pointer
  6091.                  to the string pointer for a string-related object.  String-
  6092.                  related objects and the pointers this finds for each are:
  6093.  
  6094.                      G_STRING    The ob_spec string pointer.
  6095.                      G_BUTTON    The ob_spec button-text pointer.
  6096.                      G_TITLE     The ob_spec title-text pointer.
  6097.                      G_TEXT      The te_ptext pointer.
  6098.                      G_FTEXT     The te_ptext pointer.
  6099.                      G_BOXTEXT   The te_ptext pointer.
  6100.                      G_FBOXTEXT  The te_ptext pointer.
  6101.                      G_ICON      The ib_ptext pointer.
  6102.                      G_TSCOLL    The currently-selected string.
  6103.  
  6104.                  This function understands how to find the real string
  6105.                  pointer for each of these object types.  It copes with the
  6106.                  INDIRECT flag.  It understands extended G_USERDEF objects,
  6107.                  where ob_spec has been moved into the XUSERBLK.
  6108.  
  6109.                  If you're not used to working with double-indirect pointers,
  6110.                  I recommend that you consider using one of the functions
  6111.                  listed under See Also, above.
  6112.  
  6113.        Source:   aesfuncs\objppstr.c
  6114.  
  6115.  
  6116.  
  6117.  
  6118.  
  6119.  
  6120.  
  6121.  
  6122.  
  6123.  
  6124.  
  6125.  
  6126.  
  6127.  
  6128.  
  6129.  
  6130.  
  6131.  
  6132.        
  6133.        ======================================================================
  6134.        GemFast v1.8                                                   Page 88
  6135.  
  6136.  
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.  
  6143.        short obj_rbfind(OBJECT *ptree, short parent, short rbstate)
  6144.        ______________________________________________________________________
  6145.  
  6146.        Summary:  Finds the selected button in a group of radio buttons.
  6147.  
  6148.        Input:    The ptree parameter is a pointer to the object tree.
  6149.  
  6150.                  The parent parameter is the index of the parent which
  6151.                  contains the radio buttons.
  6152.  
  6153.                  The rbstate parameter is the ob_state mask to look for.
  6154.  
  6155.        Returns:  The index of the selected object, or NO_OBJECT (-1) if no
  6156.                  radio buttons are in the desired state.
  6157.  
  6158.        See Also: obj_rbselect()
  6159.  
  6160.        Details:  This function walks through the children of the specified
  6161.                  parent.  For each child object with the RBUTTON bit set in
  6162.                  the ob_flags, it does an AND of the child's ob_state against
  6163.                  the rbstate parameter.  It returns the index of the first
  6164.                  child object which has a non-zero result from the AND.  It
  6165.                  returns NO_OBJECT if the result was zero for all children.
  6166.  
  6167.                  The most common use of this function is to pass SELECTED for
  6168.                  the rbstate parameter.  Sometimes it's handy to use OUTLINED
  6169.                  or another state to indicate selection of an object, so this
  6170.                  function allows any state bit(s) to be specified.  If you
  6171.                  pass a combination of bits, (ie, (SELECTED|OUTLINED)), then
  6172.                  this function finds the first radio button with either (not
  6173.                  both) of those bits set.
  6174.  
  6175.        Source:   aesfuncs\objrbutl.c
  6176.  
  6177.  
  6178.  
  6179.  
  6180.  
  6181.  
  6182.  
  6183.  
  6184.  
  6185.  
  6186.  
  6187.  
  6188.  
  6189.  
  6190.  
  6191.  
  6192.  
  6193.  
  6194.  
  6195.  
  6196.  
  6197.  
  6198.        
  6199.        ======================================================================
  6200.        GemFast v1.8                                                   Page 89
  6201.  
  6202.  
  6203.  
  6204.  
  6205.  
  6206.  
  6207.  
  6208.  
  6209.        short obj_rbselect(OBJECT *ptree, short selobj, short selstate)
  6210.        ______________________________________________________________________
  6211.  
  6212.        Summary:  De-selects current radio button, selects a new one.
  6213.  
  6214.        Input:    The ptree parameter is a pointer to the object tree.
  6215.  
  6216.                  The selobj parameter is the index of the new radio button to
  6217.                  be selected.
  6218.  
  6219.                  The selstate parameter specifies the ob_state bits which are
  6220.                  turned off in the current radio button and turned on in the
  6221.                  new one.
  6222.  
  6223.        Returns:  The index of the radio button that was selected before the
  6224.                  call, or NO_OBJECT if no buttons were previously selected.
  6225.  
  6226.        See Also: obj_rbfind()
  6227.  
  6228.        Details:  This function is the easiest way to set a given radio button
  6229.                  to a selected state.  If a button in the group is already
  6230.                  selected, this function de-selects it before selecting the
  6231.                  new button.
  6232.  
  6233.                  Note that this function does NOT update the buttons on-
  6234.                  screen, it only changes the ob_state words.  Use this for
  6235.                  setting up a dialog before displaying it.  After that, the
  6236.                  GEM forms manager updates the ob_state and the on-screen
  6237.                  object during dialog processing.
  6238.  
  6239.        Source:   aesfuncs\objrbutl.c
  6240.  
  6241.  
  6242.  
  6243.  
  6244.  
  6245.  
  6246.  
  6247.  
  6248.  
  6249.  
  6250.  
  6251.  
  6252.  
  6253.  
  6254.  
  6255.  
  6256.  
  6257.  
  6258.  
  6259.  
  6260.  
  6261.  
  6262.  
  6263.  
  6264.        
  6265.        ======================================================================
  6266.        GemFast v1.8                                                   Page 90
  6267.  
  6268.  
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.  
  6275.        void obj_sstring(OBJECT *ptree, short object, char *newstring)
  6276.        ______________________________________________________________________
  6277.  
  6278.        Summary:  Change an object's string pointer.
  6279.  
  6280.        Input:    The ptree parameter is a pointer to the tree containing the
  6281.                  object to change.
  6282.  
  6283.                  The object parameter is the index of the object to change.
  6284.  
  6285.                  The newstring parameter is a pointer to a string which is to
  6286.                  be attached to the object.
  6287.  
  6288.        Returns:  Nothing.
  6289.  
  6290.        See Also: rsc_sstrings() obj_gstring() obj_gvalue() obj_svalue()
  6291.  
  6292.        Details:  This function attaches a string pointer to a string-related
  6293.                  object.  
  6294.  
  6295.                  In standard GEM programming, an object's ob_spec field
  6296.                  points to the string.  In GemFast, however, an increasing
  6297.                  number of extended objects have their string pointers stored
  6298.                  in an extension block, and the object's ob_spec points at
  6299.                  the extension block. 
  6300.  
  6301.                  This function understands how to find the real string
  6302.                  pointer for all string-related object types.  It copes with
  6303.                  the INDIRECT flag.  It understands extended G_USERDEF
  6304.                  objects, where ob_spec has been moved into the XUSERBLK.
  6305.  
  6306.                  When an object is not string-related, the obj_svalue()
  6307.                  function should be used instead of this function.
  6308.  
  6309.        Source:   aesfuncs\objppstr.c
  6310.  
  6311.  
  6312.  
  6313.  
  6314.  
  6315.  
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329.  
  6330.        
  6331.        ======================================================================
  6332.        GemFast v1.8                                                   Page 91
  6333.  
  6334.  
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.  
  6341.        void obj_stchange(OBJECT *ptree, short object, short newstate,
  6342.                          short drawflag [, GRECT *cliprect ])
  6343.        ______________________________________________________________________
  6344.  
  6345.        Summary:  Change an object's state, with optional redraw.
  6346.  
  6347.        Input:    The ptree parameter is a pointer to the tree containing the
  6348.                  object to change.
  6349.  
  6350.                  The object parameter is the index of the object to change.
  6351.  
  6352.                  The newstate parameter specifies which object state bits to
  6353.                  change; details below.  
  6354.  
  6355.                  The drawflag parameter specifies whether the object is to be
  6356.                  visually updated on the screen, use one of the following:
  6357.  
  6358.                    OBJ_NODRAW   (0) -    Don't update the screen.
  6359.                    OBJ_WITHDRAW (1) -    Update the screen.
  6360.                    OBJ_CLIPDRAW (2) -    Update the screen with clipping.
  6361.  
  6362.                  The cliprect parameter is an optional pointer to a rectangle
  6363.                  which will be used to clip the redraw of the object.  This
  6364.                  parameter is only used when the drawflag parameter is equal
  6365.                  to OBJ_CLIPDRAW.
  6366.  
  6367.        Returns:  Nothing.
  6368.  
  6369.        See Also:
  6370.  
  6371.        Details:  This function provides a simple way to change the object
  6372.                  state bits for any object.
  6373.  
  6374.                  If the high bit of the newstate parameter is set, an AND is
  6375.                  used to mask off bits in the object flags.  If the high bit
  6376.                  is not set, an OR is used to set bits in the object flags. 
  6377.                  This allows a newstate value of SELECTED to set the bit, and
  6378.                  a value of ~SELECTED to unset it.
  6379.  
  6380.                  When the drawflag parameter is non-zero, an objc_draw() call
  6381.                  is automatically done after the flags are changed.  The
  6382.                  objc_draw() is always done starting at object and drawing to
  6383.                  MAX_DEPTH, and the draw is clipped to the on-screen
  6384.                  rectangle of the dialog that contains it.  
  6385.  
  6386.                  When your dialog is in a window or another situation in
  6387.                  which you might need to clip the redraw, use the
  6388.                  OBJ_CLIPDRAW option, and provide a pointer to the clipping
  6389.                  rectangle.  If the draw option is not CLIPDRAW, the clip
  6390.                  pointer need not be specified.
  6391.  
  6392.        Source:   aesfuncs\objstchg.c
  6393.  
  6394.  
  6395.  
  6396.        
  6397.        ======================================================================
  6398.        GemFast v1.8                                                   Page 92
  6399.  
  6400.  
  6401.  
  6402.  
  6403.  
  6404.  
  6405.  
  6406.  
  6407.        void obj_svalue(OBJECT *ptree, short object, long newvalue)
  6408.        ______________________________________________________________________
  6409.  
  6410.        Summary:  Change an object's associated value.
  6411.  
  6412.        Input:    The ptree parameter is a pointer to the tree containing the
  6413.                  object to change.
  6414.  
  6415.                  The object parameter is the index of the object to change.
  6416.  
  6417.                  The newvalue parameter is a longword value to be stored with
  6418.                  the object.
  6419.  
  6420.        Returns:  Nothing.
  6421.  
  6422.        See Also: obj_gvalue() obj_gstring() obj_sstring()
  6423.  
  6424.        Details:  This function sets a new value to be associated with an
  6425.                  object.
  6426.  
  6427.                  In standard GEM programming, an object's ob_spec field holds
  6428.                  the object's value, which is usually related to drawing the
  6429.                  value in some way.  In GemFast, however, a number of
  6430.                  extended objects have numeric values associated with them
  6431.                  which are stored in an extension block, and the object's
  6432.                  ob_spec points at the extension block. 
  6433.  
  6434.                  When an object is string-related, the obj_sstring() function
  6435.                  should be used instead of this function.
  6436.  
  6437.                  Note that this function does NOT trigger an automatic update
  6438.                  in the appearance of an object that is currently on-screen;
  6439.                  a separate objc_draw() call would be required to do that.
  6440.  
  6441.        Source:   aesfuncs\objgspec.c
  6442.  
  6443.  
  6444.  
  6445.  
  6446.  
  6447.  
  6448.  
  6449.  
  6450.  
  6451.  
  6452.  
  6453.  
  6454.  
  6455.  
  6456.  
  6457.  
  6458.  
  6459.  
  6460.  
  6461.  
  6462.        
  6463.        ======================================================================
  6464.        GemFast v1.8                                                   Page 93
  6465.  
  6466.  
  6467.  
  6468.  
  6469.  
  6470.  
  6471.  
  6472.  
  6473.        short obj_xtfind(OBJECT *ptree, short parent, short xtype)
  6474.        ______________________________________________________________________
  6475.  
  6476.        Summary:  Finds the object with the specified extended object type.
  6477.  
  6478.        Input:    The ptree parameter is a pointer to the tree.
  6479.  
  6480.                  The parent parameter is the index of the parent which
  6481.                  contains the objects to be scanned.
  6482.  
  6483.                  The xtype parameter specifies the extended object type to
  6484.                  search for.
  6485.  
  6486.        Returns:  The index of the object having the specified extended type,
  6487.                  or NO_OBJECT (-1) if nothing was found.
  6488.  
  6489.        See Also: obj_bmbuttons() rsc_sxtypes()
  6490.  
  6491.        Details:  This function scans the children of the specified parent
  6492.                  object.  It compares the extended object type in each child
  6493.                  to the specified xtype, and returns the index of the first
  6494.                  object which matches.  If none of the children have the
  6495.                  specified extended type, NO_OBJECT is returned.
  6496.  
  6497.                  Extended object types are stored in the upper byte of the
  6498.                  ob_type word.  GEM only uses the lower 8 bits of the ob_type
  6499.                  value, and ignores any value in the upper 8 bits.  All
  6500.                  GemFast library routines which look at or set the ob_type
  6501.                  field also work with the lower 8 bits, and ignore (or
  6502.                  preserve) the upper 8 bits.
  6503.  
  6504.                  So, you can stuff any 8-bit value you want into the upper 8
  6505.                  bits of the ob_type word.  There's a zillion things you can
  6506.                  do with it.  
  6507.  
  6508.        Source:   aesfuncs\objxtfind.c
  6509.  
  6510.  
  6511.  
  6512.  
  6513.  
  6514.  
  6515.  
  6516.  
  6517.  
  6518.  
  6519.  
  6520.  
  6521.  
  6522.  
  6523.  
  6524.  
  6525.  
  6526.  
  6527.  
  6528.        
  6529.        ======================================================================
  6530.        GemFast v1.8                                                   Page 94
  6531.  
  6532.  
  6533.  
  6534.  
  6535.  
  6536.  
  6537.  
  6538.  
  6539.        void obj_xywh(OBJECT *ptree, short object, GRECT *prect)
  6540.        ______________________________________________________________________
  6541.  
  6542.        Summary:  Get the xywh values for an object.
  6543.  
  6544.        Input:    The ptree parameter is a pointer to the object tree.
  6545.  
  6546.                  The object parameter is the index of the object.
  6547.  
  6548.                  The prect parameter is a pointer to the rectangle into which
  6549.                  the object's xywh values are returned.
  6550.  
  6551.        Returns:  Nothing.
  6552.  
  6553.        See Also: obj_offxywh() obj_clcalc() 
  6554.  
  6555.        Details:  This function gets the xywh values for the object.  The
  6556.                  values returned are straight from the object; they are
  6557.                  relative to the object's parent, not to the screen.
  6558.  
  6559.        Source:   aesfuncs\objoxywh.c
  6560.  
  6561.  
  6562.  
  6563.  
  6564.  
  6565.  
  6566.  
  6567.  
  6568.  
  6569.  
  6570.  
  6571.  
  6572.  
  6573.  
  6574.  
  6575.  
  6576.  
  6577.  
  6578.  
  6579.  
  6580.  
  6581.  
  6582.  
  6583.  
  6584.  
  6585.  
  6586.  
  6587.  
  6588.  
  6589.  
  6590.  
  6591.  
  6592.  
  6593.  
  6594.        
  6595.        ======================================================================
  6596.        GemFast v1.8                                                   Page 95
  6597.  
  6598.  
  6599.  
  6600.  
  6601.  
  6602.  
  6603.  
  6604.  
  6605.        Miscellanious Utilities Library
  6606.  
  6607.  
  6608.                  The miscellanious utilities library contains functions which
  6609.                  are commonly used to perform standard calculations used in
  6610.                  GEM programming.  It also includes several function-like
  6611.                  macros that let you use shorthand notation to perform common
  6612.                  actions.
  6613.  
  6614.                  In reading the descriptions of the rectangle calculation
  6615.                  functions, it is important to keep in mind that these
  6616.                  functions never affect pixels; they work only with the
  6617.                  rectangle structures that describe areas of pixels. 
  6618.                  (Sometimes the wording gets confusing.  "Copies a rectangle"
  6619.                  means the xywh values are copied, not the pixels the
  6620.                  rectangle describes.)
  6621.  
  6622.  
  6623.  
  6624.  
  6625.  
  6626.  
  6627.  
  6628.  
  6629.  
  6630.  
  6631.  
  6632.  
  6633.  
  6634.  
  6635.  
  6636.  
  6637.  
  6638.  
  6639.  
  6640.  
  6641.  
  6642.  
  6643.  
  6644.  
  6645.  
  6646.  
  6647.  
  6648.  
  6649.  
  6650.  
  6651.  
  6652.  
  6653.  
  6654.  
  6655.  
  6656.  
  6657.  
  6658.  
  6659.  
  6660.        
  6661.        ======================================================================
  6662.        GemFast v1.8                                                   Page 96
  6663.  
  6664.  
  6665.  
  6666.  
  6667.  
  6668.  
  6669.  
  6670.  
  6671.        void rc_confine(void *boundrect, void *destrect)
  6672.        ______________________________________________________________________
  6673.  
  6674.        Summary:  Confine a rectangle to the inside of another rectangle.
  6675.  
  6676.        Input:    The boundrect parameter is a pointer to the boundary
  6677.                  rectangle within which the destination is confined.
  6678.  
  6679.                  The destrect parameter is a pointer to the destination
  6680.                  rectangle.  This rectangle supplies input values and
  6681.                  receives the results of the calculation; details below.
  6682.  
  6683.        Returns:  Nothing.
  6684.  
  6685.        See Also: frm_confine()
  6686.  
  6687.        Details:  This function forces the destination rectangle to be
  6688.                  confined within the boundary rectangle.  
  6689.  
  6690.                  On entry, the destination rectangle describes an initial
  6691.                  xywh area.  If any part of that area is outside the boundary
  6692.                  rectangle, the x and y values of the destination are
  6693.                  adjusted to keep it within the boundary.  
  6694.  
  6695.                  The width and height of the destination are never changed. 
  6696.                  It assumed (but not at all required) that the destination
  6697.                  rectangle will fit within the boundary.
  6698.  
  6699.                  If the destination rectangle is wider or taller than the
  6700.                  boundary, it is aligned with the upper or left corner of the
  6701.                  boundary in that dimension.  In other words, if the boundary
  6702.                  were the physical screen, the x/y values would never be set
  6703.                  to negative values.  This allows you to call this function
  6704.                  to align rectangle then call rc_intersect() to clip if
  6705.                  clipping is a requirement.
  6706.  
  6707.        Example:  Suppose you want to center a window over the current mouse
  6708.                  location.  You get the mouse x/y and set the window
  6709.                  rectangle's x/y so that it's centered over the mouse
  6710.                  location.  If the mouse was near the edge of the screen, the
  6711.                  window's xywh might now describe some off-screen area, so
  6712.                  you do:
  6713.  
  6714.                      rc_confine(&gl_rwdesk, &windrect);
  6715.                      winx_set(whandle, WF_CURRXYWH, &windrect);
  6716.  
  6717.                  This forces the edges of the window to align with the
  6718.                  desktop if the window would have been partly off-screen
  6719.                  before the call.  You know the window isn't bigger than the
  6720.                  desktop, so this sequence will always force the entire
  6721.                  window to appear on-screen.
  6722.  
  6723.        Source:   aesfuncs\rcconfin.c
  6724.  
  6725.  
  6726.        
  6727.        ======================================================================
  6728.        GemFast v1.8                                                   Page 97
  6729.  
  6730.  
  6731.  
  6732.  
  6733.  
  6734.  
  6735.  
  6736.  
  6737.        void rc_copy(void *sourcerect, void *destrect)
  6738.        ______________________________________________________________________
  6739.  
  6740.        Summary:  Copy the source rectangle to the destination rectangle.
  6741.  
  6742.        Input:    The sourcerect parameter is a pointer to the source
  6743.                  rectangle.
  6744.  
  6745.                  The destrect parameter is a pointer to the destination
  6746.                  rectangle.
  6747.  
  6748.        Returns:  Nothing.
  6749.  
  6750.        See Also:
  6751.  
  6752.        Details:  This copies a rectangle, or more accurately, 8 bytes of
  6753.                  word-aligned data.
  6754.  
  6755.        Source:   aesfuncs\rccopy.c  
  6756.  
  6757.  
  6758.  
  6759.  
  6760.  
  6761.  
  6762.  
  6763.  
  6764.  
  6765.  
  6766.  
  6767.  
  6768.  
  6769.  
  6770.  
  6771.  
  6772.  
  6773.  
  6774.  
  6775.  
  6776.  
  6777.  
  6778.  
  6779.  
  6780.  
  6781.  
  6782.  
  6783.  
  6784.  
  6785.  
  6786.  
  6787.  
  6788.  
  6789.  
  6790.  
  6791.  
  6792.        
  6793.        ======================================================================
  6794.        GemFast v1.8                                                   Page 98
  6795.  
  6796.  
  6797.  
  6798.  
  6799.  
  6800.  
  6801.  
  6802.  
  6803.        int rc_equal(void *rect1, void *rect2)
  6804.        ______________________________________________________________________
  6805.  
  6806.        Summary:  Returns TRUE if two rectangles are identical.
  6807.  
  6808.        Input:    The rect1 and rect2 parameters are pointers to the
  6809.                  rectangles to be compared.
  6810.  
  6811.        Returns:  TRUE (non-zero) if the rectangles are identical, FALSE (0)
  6812.                  if they're not.
  6813.  
  6814.        See Also:
  6815.  
  6816.        Details:  For the rectangles to be identical, all four values (xywh)
  6817.                  must be equal.  More accurately, this function compares 8
  6818.                  bytes of word-aligned data.
  6819.  
  6820.        Source:   aesfuncs\rcequal.c
  6821.  
  6822.  
  6823.  
  6824.  
  6825.  
  6826.  
  6827.  
  6828.  
  6829.  
  6830.  
  6831.  
  6832.  
  6833.  
  6834.  
  6835.  
  6836.  
  6837.  
  6838.  
  6839.  
  6840.  
  6841.  
  6842.  
  6843.  
  6844.  
  6845.  
  6846.  
  6847.  
  6848.  
  6849.  
  6850.  
  6851.  
  6852.  
  6853.  
  6854.  
  6855.  
  6856.  
  6857.  
  6858.        
  6859.        ======================================================================
  6860.        GemFast v1.8                                                   Page 99
  6861.  
  6862.  
  6863.  
  6864.  
  6865.  
  6866.  
  6867.  
  6868.  
  6869.        GRECT * rc_gadjust(GRECT *prect, short hadjust, short vadjust)
  6870.        ______________________________________________________________________
  6871.  
  6872.        Summary:  Adjust the size of a GRECT rectangle.
  6873.  
  6874.        Input:    The prect parameter is a pointer to the rectangle to be
  6875.                  adjusted.
  6876.  
  6877.                  The hadjust parameter is the number of pixels to adjust by
  6878.                  in the horizontal direction.  Positive values enlarge the
  6879.                  rectangle; negative values shrink it.
  6880.  
  6881.                  The vadjust parameter is the number of pixels to adjust by
  6882.                  in the vertical direction.  Positive values enlarge the
  6883.                  rectangle; negative values shrink it.
  6884.  
  6885.        Returns:  The pointer to the rectangle.
  6886.  
  6887.        See Also: rc_vadjust()
  6888.  
  6889.        Details:  This function makes a GRECT rectangle describe a larger or
  6890.                  smaller area.  The rectangle remains centered on its
  6891.                  original location, and grows or shrinks equally on each side
  6892.                  in the adjusted dimension(s).
  6893.  
  6894.                  The x/y locations are never allowed to go negative (they are
  6895.                  clipped to zero).  The w/h sizes are never allowed to fall
  6896.                  below 1.
  6897.  
  6898.        Source:   aesfuncs\rcadjust.c
  6899.  
  6900.  
  6901.  
  6902.  
  6903.  
  6904.  
  6905.  
  6906.  
  6907.  
  6908.  
  6909.  
  6910.  
  6911.  
  6912.  
  6913.  
  6914.  
  6915.  
  6916.  
  6917.  
  6918.  
  6919.  
  6920.  
  6921.  
  6922.  
  6923.  
  6924.        
  6925.        ======================================================================
  6926.        GemFast v1.8                                                  Page 100
  6927.  
  6928.  
  6929.  
  6930.  
  6931.  
  6932.  
  6933.  
  6934.  
  6935.        VRECT * rc_gtov(GRECT *pgrect, VRECT *pvrect)
  6936.        ______________________________________________________________________
  6937.  
  6938.        Summary:  Convert a GRECT rectangle to a VRECT rectangle.
  6939.  
  6940.        WARNING:  There was a major change in this function's behavior in v1.8
  6941.                  that will affect existing code; details below.
  6942.  
  6943.        Input:    The pgrect parameter is a pointer to the source GRECT.
  6944.  
  6945.                  The pvrect parameter is a pointer to the destination VRECT.
  6946.  
  6947.        Returns:  The pointer to the destination VRECT.
  6948.  
  6949.        See Also: rc_vtog()
  6950.  
  6951.        Details:  The source GRECT is converted to the equivalent VRECT.  Do
  6952.                  NOT specify the same rectangle for source and destination.
  6953.  
  6954.                  A GRECT describes an area by x, y, width and height.  A
  6955.                  VRECT describes an area by the x and y coordinates of
  6956.                  diagonally opposite corners.  This function translates a
  6957.                  GRECT to a VRECT as follows:
  6958.  
  6959.                      pvrect->v_x1 = pgrect->g_x;
  6960.                      pvrect->v_y1 = pgrect->g_y;
  6961.                      pvrect->v_x2 = pgrect->g_x + pgrect->g_w - 1;
  6962.                      pvrect->v_y2 = pgrect->g_y + pgrect->g_h - 1;
  6963.  
  6964.                  GemFast versions prior to v1.8 did not apply the -1
  6965.                  correction to the second pair of coordinates.  This was just
  6966.                  plain wrong, and it had to be fixed even though you may now
  6967.                  have to go remove some -1 expressions in your existing code
  6968.                  where you were compensating for the broken behavior of the
  6969.                  old versions.  ::sigh::  Sorry.
  6970.  
  6971.        Source:   aesfuncs\rcgtov.c
  6972.  
  6973.  
  6974.  
  6975.  
  6976.  
  6977.  
  6978.  
  6979.  
  6980.  
  6981.  
  6982.  
  6983.  
  6984.  
  6985.  
  6986.  
  6987.  
  6988.  
  6989.  
  6990.        
  6991.        ======================================================================
  6992.        GemFast v1.8                                                  Page 101
  6993.  
  6994.  
  6995.  
  6996.  
  6997.  
  6998.  
  6999.  
  7000.  
  7001.        int rc_intersect(GRECT *sourcerect, GRECT *destrect)
  7002.        ______________________________________________________________________
  7003.  
  7004.        Summary:  Calculate the intersecting portion of two rectangles.
  7005.  
  7006.        WARNING:  There was a minor change in this function's behavior in v1.8
  7007.                  that could affect existing code; details below.
  7008.  
  7009.        Input:    The sourcerect parameter is a pointer to the source (or
  7010.                  clipping) rectangle.
  7011.  
  7012.                  The destrect parameter is a pointer to the destination
  7013.                  rectangle.  The destination rectangle is used for input and
  7014.                  output.
  7015.  
  7016.        Returns:  TRUE (1) if the two rectangles intersect, or FALSE (0) if
  7017.                  they do not intersect.  When the return value is FALSE, the
  7018.                  contents of the destination rectangle are undetermined.
  7019.  
  7020.        See Also:
  7021.  
  7022.        Details:  You can think of this function as clipping the destination
  7023.                  rectangle against the area of the source.  
  7024.  
  7025.                  On entry, the destination rectangle describes an area that
  7026.                  may or may not have pixels in common with the source (or
  7027.                  clipping) rectangle.  This function modifies the destination
  7028.                  rectangle to describe the area where the two rectangles
  7029.                  intersect.  If they don't intersect at all, this function
  7030.                  returns FALSE, and the destination rectangle is left in an
  7031.                  undetermined state.
  7032.  
  7033.                  This function is typically used in window redraw loops, to
  7034.                  process the window rectangle list.  It can also be used in
  7035.                  general-purpose drawing situations, especially to generate a
  7036.                  clip rectangle to keep a blit from going outside the window
  7037.                  work area or off the screen.
  7038.  
  7039.                  This function does NOT clip to the physical screen
  7040.                  automatically.  Negative values in the returned x and y
  7041.                  coordinates are possible if negative values existed in the
  7042.                  inputs.
  7043.  
  7044.                  In GemFast versions prior to v1.8, this function would
  7045.                  return TRUE if the destination rectangle had a zero width or
  7046.                  height.  That doesn't make sense; if width or height is
  7047.                  zero, there's obviously no intersection of the two
  7048.                  rectangles (they may abut rather than intersect).  Starting
  7049.                  with v1.8, a zero width or height results in a FALSE return
  7050.                  value.  This shouldn't break any existing code (and should
  7051.                  make your window redraw loops a bit simpler) but as a change
  7052.                  in behavior it bears mentioning.
  7053.  
  7054.        Source:   aesfuncs\rcinters.c
  7055.  
  7056.        
  7057.        ======================================================================
  7058.        GemFast v1.8                                                  Page 102
  7059.  
  7060.  
  7061.  
  7062.  
  7063.  
  7064.  
  7065.  
  7066.  
  7067.        short rc_ptinrect(GRECT *prect, short x, short y)
  7068.        ______________________________________________________________________
  7069.  
  7070.        Summary:  Determine whether a point is inside a rectangle.
  7071.  
  7072.        Input:    The prect parameter is a pointer to the rectangle.
  7073.  
  7074.                  The x and y parameters are the coordinates of the point to
  7075.                  be checked against the rectangle.
  7076.  
  7077.  
  7078.        Returns:  TRUE if the point is inside the rectangle, FALSE if not.  A
  7079.                  point on the boundary of the rectangle is considered to be
  7080.                  inside it.
  7081.  
  7082.        See Also:
  7083.  
  7084.        Details:  This is useful for determining whether the mouse is
  7085.                  currently located within some arbitrary area.
  7086.  
  7087.        Source:   aesfuncs\rcptinre.c
  7088.  
  7089.  
  7090.  
  7091.  
  7092.  
  7093.  
  7094.  
  7095.  
  7096.  
  7097.  
  7098.  
  7099.  
  7100.  
  7101.  
  7102.  
  7103.  
  7104.  
  7105.  
  7106.  
  7107.  
  7108.  
  7109.  
  7110.  
  7111.  
  7112.  
  7113.  
  7114.  
  7115.  
  7116.  
  7117.  
  7118.  
  7119.  
  7120.  
  7121.  
  7122.        
  7123.        ======================================================================
  7124.        GemFast v1.8                                                  Page 103
  7125.  
  7126.  
  7127.  
  7128.  
  7129.  
  7130.  
  7131.  
  7132.  
  7133.        GRECT * rc_scale(GRECT *sourcerect, GRECT *destrect, short percent)
  7134.        ______________________________________________________________________
  7135.  
  7136.        Summary:  This function calculates a scaled copy of a rectangle. 
  7137.  
  7138.        Input:    The sourcerect parameter is a pointer to the source
  7139.                  rectangle.
  7140.  
  7141.                  The destrect parameter is a pointer to the destination
  7142.                  rectangle.  
  7143.  
  7144.                  The percent parameter is the scaling factor.
  7145.  
  7146.        Returns:  The pointer to the destination rectangle.
  7147.  
  7148.        See Also:
  7149.  
  7150.        Details:  This function calculates a scaled copy of a rectangle.  The
  7151.                  new rectangle describes an area larger or smaller than the
  7152.                  original, and is centered over or within the original
  7153.                  rectangle's area.
  7154.  
  7155.                  The percent parameter determines the scaling.  A value of
  7156.                  100 results in no size change.  A value of 200 doubles the
  7157.                  rectangle's area, a value of 50 halves it, a value of 5
  7158.                  yields one twentieth the original size, and so on.  The
  7159.                  resulting rectangle's width and height will never be less
  7160.                  than 1.
  7161.  
  7162.                  As an interesting side effect, using a percent value of 0
  7163.                  gives the center point of the source rectangle in the result
  7164.                  rectangle's x/y fields (and 1 in its w/h fields).  
  7165.  
  7166.        Source:   aesfuncs\rcscale.c
  7167.  
  7168.  
  7169.  
  7170.  
  7171.  
  7172.  
  7173.  
  7174.  
  7175.  
  7176.  
  7177.  
  7178.  
  7179.  
  7180.  
  7181.  
  7182.  
  7183.  
  7184.  
  7185.  
  7186.  
  7187.  
  7188.        
  7189.        ======================================================================
  7190.        GemFast v1.8                                                  Page 104
  7191.  
  7192.  
  7193.  
  7194.  
  7195.  
  7196.  
  7197.  
  7198.  
  7199.        void rc_union(GRECT *sourcerect, GRECT *destrect)
  7200.        ______________________________________________________________________
  7201.  
  7202.        Summary:  Computes a single rectangle that encompasses the area of
  7203.                  both the original rectangles.
  7204.  
  7205.        Input:    The sourcerect parameter is a pointer to the source
  7206.                  rectangle.
  7207.  
  7208.                  The destrect parameter is a pointer to the destination
  7209.                  rectangle.  The destination rectangle is used for input and
  7210.                  output.
  7211.  
  7212.        Returns:  Nothing.
  7213.  
  7214.        See Also:
  7215.  
  7216.        Details:  This function calculates the single large rectangle that
  7217.                  encompasses all the area of both rectangles.
  7218.  
  7219.                  This function does NOT clip to the physical screen
  7220.                  automatically.  Negative values in the returned x and y
  7221.                  coordinates are possible if negative values existed in the
  7222.                  inputs.
  7223.  
  7224.        Source:   aesfuncs\rcunion.c
  7225.  
  7226.  
  7227.  
  7228.  
  7229.  
  7230.  
  7231.  
  7232.  
  7233.  
  7234.  
  7235.  
  7236.  
  7237.  
  7238.  
  7239.  
  7240.  
  7241.  
  7242.  
  7243.  
  7244.  
  7245.  
  7246.  
  7247.  
  7248.  
  7249.  
  7250.  
  7251.  
  7252.  
  7253.  
  7254.        
  7255.        ======================================================================
  7256.        GemFast v1.8                                                  Page 105
  7257.  
  7258.  
  7259.  
  7260.  
  7261.  
  7262.  
  7263.  
  7264.  
  7265.        VRECT * rc_vadjust(VRECT *prect, short hadjust, short vadjust)
  7266.        ______________________________________________________________________
  7267.  
  7268.        Summary:  Adjust the size of a VRECT rectangle.
  7269.  
  7270.        Input:    The prect parameter is a pointer to the rectangle to be
  7271.                  adjusted.
  7272.  
  7273.                  The hadjust parameter is the number of pixels to adjust by
  7274.                  in the horizontal direction.  Positive values enlarge the
  7275.                  rectangle; negative values shrink it.
  7276.  
  7277.                  The vadjust parameter is the number of pixels to adjust by
  7278.                  in the vertical direction.  Positive values enlarge the
  7279.                  rectangle; negative values shrink it.
  7280.  
  7281.        Returns:  The pointer to the rectangle.
  7282.  
  7283.        See Also: rc_gadjust()
  7284.  
  7285.        Details:  This function makes a VRECT rectangle describe a larger or
  7286.                  smaller area.  The rectangle remains centered on its
  7287.                  original location, and grows or shrinks equally on each side
  7288.                  in the adjusted dimension(s).
  7289.  
  7290.                  The x/y locations are never allowed to go negative (they are
  7291.                  clipped to zero).  The w/h sizes are never allowed to fall
  7292.                  below 1.
  7293.  
  7294.        Source:   aesfuncs\rcadjust.c
  7295.  
  7296.  
  7297.  
  7298.  
  7299.  
  7300.  
  7301.  
  7302.  
  7303.  
  7304.  
  7305.  
  7306.  
  7307.  
  7308.  
  7309.  
  7310.  
  7311.  
  7312.  
  7313.  
  7314.  
  7315.  
  7316.  
  7317.  
  7318.  
  7319.  
  7320.        
  7321.        ======================================================================
  7322.        GemFast v1.8                                                  Page 106
  7323.  
  7324.  
  7325.  
  7326.  
  7327.  
  7328.  
  7329.  
  7330.  
  7331.        GRECT * rc_vtog(VRECT *pvrect, GRECT *pgrect)
  7332.        ______________________________________________________________________
  7333.  
  7334.        Summary:  Convert a VRECT rectangle to a GRECT rectangle.
  7335.  
  7336.        WARNING:  There was a major change in this function's behavior in v1.8
  7337.                  that will affect existing code; details below.
  7338.  
  7339.        Input:    The pvrect parameter is a pointer to the source VRECT.
  7340.  
  7341.                  The pgrect parameter is a pointer to the destination GRECT.
  7342.  
  7343.        Returns:  The pointer to the destination GRECT.
  7344.  
  7345.        See Also: rc_gtov()
  7346.  
  7347.        Details:  The source VRECT is converted to the equivalent GRECT.  Do
  7348.                  NOT specify the same rectangle for source and destination.
  7349.  
  7350.                  A VRECT describes an area by the x and y coordinates of
  7351.                  diagonally opposite corners.  A GRECT describes an area by
  7352.                  x, y, width and height.  This function translates a VRECT to
  7353.                  a GRECT as follows:
  7354.  
  7355.                      pgrect->g_x = pvrect->v_x1;
  7356.                      pgrect->g_y = pvrect->v_y1;
  7357.                      pgrect->g_w = pvrect->v_x1 - pvrect->g_x2 + 1;
  7358.                      pgrect->g_h = pvrect->v_y1 - pvrect->g_y2 + 1;
  7359.  
  7360.                  GemFast versions prior to v1.8 did not apply the +1
  7361.                  correction to the second pair of coordinates.  This was just
  7362.                  plain wrong, and it had to be fixed even though you may now
  7363.                  have to go remove some +1 expressions in your existing code
  7364.                  where you were compensating for the broken behavior of the
  7365.                  old versions.  ::sigh::  Sorry.
  7366.  
  7367.        Source:   aesfuncs\rcgtov.c
  7368.  
  7369.  
  7370.  
  7371.  
  7372.  
  7373.  
  7374.  
  7375.  
  7376.  
  7377.  
  7378.  
  7379.  
  7380.  
  7381.  
  7382.  
  7383.  
  7384.  
  7385.  
  7386.        
  7387.        ======================================================================
  7388.        GemFast v1.8                                                  Page 107
  7389.  
  7390.  
  7391.  
  7392.  
  7393.  
  7394.  
  7395.  
  7396.  
  7397.        MACRO RECTARRAY(GRECT *prect [or] VRECT *prect)
  7398.        ______________________________________________________________________
  7399.  
  7400.        Summary:  Pass the rectangle pointer as a short * type.
  7401.  
  7402.        Input:    The prect parameter is a pointer to a GRECT or VRECT.
  7403.  
  7404.        Returns:  N/A
  7405.  
  7406.        See Also: RECTVALS() RECTPTRS()
  7407.  
  7408.        Details:  This macro simply recasts the provided pointer to a short *
  7409.                  pointer.  It is useful primarily for passing a VRECT to a
  7410.                  VDI function that expects a pointer to an array of xy
  7411.                  coordinates.
  7412.  
  7413.                  The macro is defined as:
  7414.  
  7415.                      #define RECTARRAY(r) ((short *)(r))
  7416.  
  7417.        Example:  To draw a filled box that is described by a given GRECT, you
  7418.                  could use the following code:
  7419.  
  7420.                      GRECT *objrect;
  7421.                      VRECT  boxrect;
  7422.  
  7423.                      rc_gtov(objrect, &boxrect);     // convert to VDI coords
  7424.                      v_bar(vhandle, 2, RECTARRAY(&boxrect));
  7425.  
  7426.                  This sort of conversion is only necessary when the host
  7427.                  compiler supports prototypes.  Using this macro instead of
  7428.                  just passing &boxrect directly will make your code portable
  7429.                  to compilers that enforce pointer checking via prototypes.
  7430.  
  7431.        Source:   GEMFAST.H
  7432.  
  7433.  
  7434.  
  7435.  
  7436.  
  7437.  
  7438.  
  7439.  
  7440.  
  7441.  
  7442.  
  7443.  
  7444.  
  7445.  
  7446.  
  7447.  
  7448.  
  7449.  
  7450.  
  7451.  
  7452.        
  7453.        ======================================================================
  7454.        GemFast v1.8                                                  Page 108
  7455.  
  7456.  
  7457.  
  7458.  
  7459.  
  7460.  
  7461.  
  7462.  
  7463.        MACRO RECTPTRS(GRECT *prect)
  7464.        ______________________________________________________________________
  7465.  
  7466.        Summary:  Pass pointers to each of the rectangle's fields.
  7467.  
  7468.        Input:    The prect parameter is a pointer to a GRECT.
  7469.  
  7470.        Returns:  N/A
  7471.  
  7472.        See Also: RECTVALS() RECTARRAY()
  7473.  
  7474.        Details:  This macro expands to a set of four pointers to the four
  7475.                  fields of the GRECT structure.  It provides a shorthand
  7476.                  notation for GEM functions which return xywh values via
  7477.                  pointers you provide in the call.
  7478.  
  7479.                  The macro is defined as:
  7480.  
  7481.                      #define RECTPTRS(r)  &((r)->g_x), &((r)->g_y), \
  7482.                                           &((r)->g_w), &((r)->g_h)
  7483.  
  7484.        Example:  To obtain the current coordinates of a window, use:
  7485.  
  7486.                      GRECT wrect;
  7487.  
  7488.                      wind_get(whandle, WF_CURRXYWH, RECTPTRS(&wrect));
  7489.  
  7490.                  This is equivalent to coding:
  7491.  
  7492.                      wind_get(whandle, WF_CURRXYWH,
  7493.                          &wrect.g_x, &wrect.g_y, &wrect.g_w, &wrect.g_h); 
  7494.  
  7495.                  It also works with pointers to GRECTs as follows:
  7496.  
  7497.                      GRECT *wrect;
  7498.  
  7499.                      wind_get(whandle, WF_CURRXYWH, RECTPTRS(wrect));
  7500.  
  7501.        Source:   GEMFAST.H
  7502.  
  7503.  
  7504.  
  7505.  
  7506.  
  7507.  
  7508.  
  7509.  
  7510.  
  7511.  
  7512.  
  7513.  
  7514.  
  7515.  
  7516.  
  7517.  
  7518.        
  7519.        ======================================================================
  7520.        GemFast v1.8                                                  Page 109
  7521.  
  7522.  
  7523.  
  7524.  
  7525.  
  7526.  
  7527.  
  7528.  
  7529.        MACRO RECTVALS(GRECT *prect)
  7530.        ______________________________________________________________________
  7531.  
  7532.        Summary:  Pass the values of each of the rectangle's fields.
  7533.  
  7534.        Input:    The prect parameter is a pointer to a GRECT.
  7535.  
  7536.        Returns:  N/A
  7537.  
  7538.        See Also: RECTPTRS() RECTARRAY()
  7539.  
  7540.        Details:  This macro expands to a set of four values from the four
  7541.                  fields of the GRECT structure.  It provides a shorthand
  7542.                  notation for GEM functions which accept xywh values as four
  7543.                  discreet parameters.
  7544.  
  7545.                  The macro is defined as:
  7546.  
  7547.                      #define RECTVALS(r)  (r)->g_x, (r)->g_y, \
  7548.                                           (r)->g_w, (r)->g_h
  7549.  
  7550.        Example:  To set the current coordinates of a window, use:
  7551.  
  7552.                      GRECT wrect;
  7553.  
  7554.                      // put some values into wrect somehow
  7555.                      wind_set(whandle, WF_CURRXYWH, RECTVALS(&wrect));
  7556.  
  7557.                  This is equivalent to coding:
  7558.  
  7559.                      wind_set(whandle, WF_CURRXYWH,
  7560.                          wrect.g_x, wrect.g_y, wrect.g_w, wrect.g_h); 
  7561.  
  7562.                  It also works with pointers to GRECTs as follows:
  7563.  
  7564.                      GRECT *wrect;
  7565.  
  7566.                      wind_set(whandle, WF_CURRXYWH, RECTVALS(wrect));
  7567.  
  7568.        Source:   GEMFAST.H
  7569.  
  7570.  
  7571.  
  7572.  
  7573.  
  7574.  
  7575.  
  7576.  
  7577.  
  7578.  
  7579.  
  7580.  
  7581.  
  7582.  
  7583.  
  7584.        
  7585.        ======================================================================
  7586.        GemFast v1.8                                                  Page 110
  7587.  
  7588.  
  7589.  
  7590.  
  7591.  
  7592.  
  7593.  
  7594.  
  7595.        void wc_scroll_calc(short curline, short datalines, short windowlines
  7596.                            short *pslidesize, short *pslidepos)
  7597.        ______________________________________________________________________
  7598.  
  7599.        Summary:  Calculate the slider size and position for a window.
  7600.  
  7601.        Input:    The curline parameter is a value between 0 and datalines
  7602.                  which is the current line at the top of the window.
  7603.  
  7604.                  The datalines parameter is the number of lines of data
  7605.                  available to be displayed.
  7606.  
  7607.                  The windowlines parameter is the number of lines the window
  7608.                  can display at its current size.
  7609.  
  7610.                  The pslidesize parameter is a pointer to a short into which
  7611.                  the slider size will be returned.  The returned value will
  7612.                  be in the range of -1 <= value <= 1000, where -1 indicates
  7613.                  (to GEM, via a wind_set() call) that the system-defined
  7614.                  minimum size should be used.
  7615.  
  7616.                  The pslidpos parameter is a pointer to a short into which
  7617.                  the slider position will be returned.  The returned value
  7618.                  will be in the range of 1 <= value <= 1000.
  7619.  
  7620.        Returns:  Nothing.
  7621.  
  7622.        See Also:
  7623.  
  7624.        Details:  This function assists you in calculating window slider size
  7625.                  and position values appropriate for use in a wind_set()
  7626.                  call.  It automatically enforces a reasonable minimum value
  7627.                  for the slider size.
  7628.  
  7629.                  While the parameter names seem to indicate that this
  7630.                  function works on the basis of lines of text, these values
  7631.                  are really expressed in arbitrary units.  A 'line' is one
  7632.                  quantum of information that can be displayed in a window. 
  7633.                  For graphics work, it may represent a band of image that's
  7634.                  10 pixels high or wide, for example.  
  7635.  
  7636.        Source:   aesfuncs\wcscrcal.c
  7637.  
  7638.  
  7639.  
  7640.  
  7641.  
  7642.  
  7643.  
  7644.  
  7645.  
  7646.  
  7647.  
  7648.  
  7649.  
  7650.        
  7651.        ======================================================================
  7652.        GemFast v1.8                                                  Page 111
  7653.  
  7654.  
  7655.  
  7656.  
  7657.  
  7658.  
  7659.  
  7660.  
  7661.        Resource Library
  7662.  
  7663.  
  7664.                  The resource library contains functions which manipulate an
  7665.                  entire object tree, or a list of objects in a tree.  It
  7666.                  includes functions that simplify access to the strings in
  7667.                  your dialogs, functions that alter the appearance of the
  7668.                  buttons in a dialog, and a few miscellaneous things.
  7669.  
  7670.  
  7671.  
  7672.  
  7673.  
  7674.  
  7675.  
  7676.  
  7677.  
  7678.  
  7679.  
  7680.  
  7681.  
  7682.  
  7683.  
  7684.  
  7685.  
  7686.  
  7687.  
  7688.  
  7689.  
  7690.  
  7691.  
  7692.  
  7693.  
  7694.  
  7695.  
  7696.  
  7697.  
  7698.  
  7699.  
  7700.  
  7701.  
  7702.  
  7703.  
  7704.  
  7705.  
  7706.  
  7707.  
  7708.  
  7709.  
  7710.  
  7711.  
  7712.  
  7713.  
  7714.  
  7715.  
  7716.        
  7717.        ======================================================================
  7718.        GemFast v1.8                                                  Page 112
  7719.  
  7720.  
  7721.  
  7722.  
  7723.  
  7724.  
  7725.  
  7726.  
  7727.        short rsc_cubuttons(OBJECT *ptree)
  7728.        ______________________________________________________________________
  7729.  
  7730.        Summary:  Change all buttons in a dialog tree to CUA-style buttons.
  7731.  
  7732.        Input:    The ptree parameter is a pointer to the dialog tree to be
  7733.                  modified.
  7734.  
  7735.        Returns:  Zero for success, or a negative (TOS) error code.
  7736.  
  7737.        See Also: rsc_rrbuttons()
  7738.  
  7739.        Details:  This function modifies the visual appearance of all non-exit
  7740.                  buttons in a dialog, transforming them to passive G_USERDEF
  7741.                  objects and supplying a custom drawing function.  The visual
  7742.                  style of selection (on/off) and radio buttons is similar to
  7743.                  the CUA standard used by Windows 3 and other systems.  Exit
  7744.                  buttons aren't  changed, because GEM exit buttons are
  7745.                  already CUA-ish.
  7746.  
  7747.                  This function lets you use a standard GEM resource editor to
  7748.                  create dialogs using GEM buttons.  The only restriction on
  7749.                  resource design is that your buttons' boxes should be at
  7750.                  least 3 characters wider than the strings they contain.  A
  7751.                  CUA-style selection or radio button includes a graphic box
  7752.                  and whitespace equal to 3 character widths in front of the
  7753.                  displayed button string.
  7754.  
  7755.                  This function allocates a block of memory to contain the
  7756.                  XUSERBLK structures that it attaches to the button objects. 
  7757.                  If the allocation fails, ENSMEM (-39) is returned.  It is
  7758.                  also possible to get a return value of -35 (no more handles)
  7759.                  if the VDI shared workstation can't be opened.
  7760.  
  7761.                  Each selection or radio button object in the dialog tree is
  7762.                  transformed into an extended G_USERDEF object.  The main
  7763.                  implication of this transformation is that the button's
  7764.                  string pointer is moved from the object's ob_spec field to
  7765.                  the XUSERBLK ob_spec field.  If you use obj_gstring(),
  7766.                  obj_sstring(), rsc_gstrings(), and/or rsc_sstrings() instead
  7767.                  of directly accessing the object's ob_spec field, you don't
  7768.                  have to worry about this at all.
  7769.  
  7770.                  Other than the button string pointer, you can continue to
  7771.                  access the buttons in the usual way, directly accessing the
  7772.                  ob_flags and ob_state fields as needed.  In addition, you
  7773.                  can use the extended object type as you wish; this function
  7774.                  changes the lower 8 bits of the ob_type field to G_USERDEF,
  7775.                  but leaves the upper 8 bits alone.
  7776.  
  7777.        Source:   aesfuncs\rsccubtn.c
  7778.  
  7779.  
  7780.  
  7781.  
  7782.        
  7783.        ======================================================================
  7784.        GemFast v1.8                                                  Page 113
  7785.  
  7786.  
  7787.  
  7788.  
  7789.  
  7790.  
  7791.  
  7792.  
  7793.        void rsc_gstrings(OBJECT *ptree, int object, char **ppstr, ...)
  7794.        ______________________________________________________________________
  7795.  
  7796.        Summary:  Get the string pointers for one or more string-related
  7797.                  objects in a dialog tree.
  7798.  
  7799.        Input:    The ptree parameter is a pointer to the dialog tree
  7800.                  containing the string-related objects.
  7801.  
  7802.                  The object parameter is the index of the first object for
  7803.                  which you want to retrieve the string pointer.
  7804.  
  7805.                  The ppstr parameter is a pointer to your variable
  7806.                  (char* type).  The string pointer for the object is stored
  7807.                  here.
  7808.  
  7809.                  The ... parameters are additional object/ppstr pairs.  Use
  7810.                  an object number of -1 to indicate the end of the list.
  7811.  
  7812.        Returns:  Nothing.
  7813.  
  7814.        See Also: rsc_sstrings() obj_ppstring()
  7815.  
  7816.        Details:  This allows you to easily initialize your local string
  7817.                  pointers to point at string-related objects in a dialog
  7818.                  tree.  The description of the obj_ppstring() function
  7819.                  contains details on what objects are string-related.
  7820.  
  7821.                  You must specify at least one object/ppstr pair following
  7822.                  the tree pointer in the call.  You can specify any number of
  7823.                  pairs following the first one to retrieve the pointers for
  7824.                  more than one object with a single call.  Specify -1 for the
  7825.                  index following the last pair.  (There's no need to supply a
  7826.                  pointer to go with the -1 object index.)  
  7827.  
  7828.                  This function understands how to find the real string
  7829.                  pointer for each of string-related object type.  It copes
  7830.                  with the INDIRECT flag.  It understands extended G_USERDEF
  7831.                  objects, where ob_spec has been moved into the XUSERBLK.
  7832.  
  7833.                  This function gives you pointers which point into the
  7834.                  resource data area.  If you modify the strings using these
  7835.                  pointers, please remember that your resource editor has only
  7836.                  allocated enough space in the resource data to hold the
  7837.                  strings as you typed them when you built the object.  In
  7838.                  other words, you can define a button as "OK", and then at
  7839.                  runtime use this function to get a pointer to the button
  7840.                  text.  But, if you do something like
  7841.                      strcpy(buttonptr, "Not Okay"); 
  7842.                  then you end up corrupting the resource data, because you
  7843.                  copied an 8-character string into a space only 2 characters
  7844.                  wide.  
  7845.  
  7846.                  You can avoid this modify-in-place problem by defining your
  7847.  
  7848.        
  7849.        ======================================================================
  7850.        GemFast v1.8                                                  Page 114
  7851.  
  7852.  
  7853.  
  7854.  
  7855.  
  7856.  
  7857.  
  7858.  
  7859.                  strings big enough in the resource editor, or by using
  7860.                  rsc_sstrings() to make the objects point to strings
  7861.                  allocated within your program rather than working with the
  7862.                  strings directly in the resource data area.  In this case,
  7863.                  you can define dummy strings (I use "x") in the resource
  7864.                  editor to avoid wasting space, since the strings you define
  7865.                  are not used at runtime anyway after you use rsc_sstrings()
  7866.                  to point objects at your program-defined strings.
  7867.  
  7868.        Example:  To retrieve the string pointers for a button and a text
  7869.                  object, use code such as the following:
  7870.  
  7871.                      char *editstring;
  7872.                      char *btnstring;
  7873.           
  7874.                      void dial_init()
  7875.                      {
  7876.                          rsc_gstrings(mydialog, 
  7877.                                          EDITOBJ, &editstring,
  7878.                                          BUTTON1, &btnstring,
  7879.                                          -1);
  7880.                          *editstring = 0; // empty the edit string
  7881.                          strcpy(btnstring, " Go "); // set the button text
  7882.                      }
  7883.  
  7884.        Source:   aesfuncs\rscgstr.c
  7885.  
  7886.  
  7887.  
  7888.  
  7889.  
  7890.  
  7891.  
  7892.  
  7893.  
  7894.  
  7895.  
  7896.  
  7897.  
  7898.  
  7899.  
  7900.  
  7901.  
  7902.  
  7903.  
  7904.  
  7905.  
  7906.  
  7907.  
  7908.  
  7909.  
  7910.  
  7911.  
  7912.  
  7913.  
  7914.        
  7915.        ======================================================================
  7916.        GemFast v1.8                                                  Page 115
  7917.  
  7918.  
  7919.  
  7920.  
  7921.  
  7922.  
  7923.  
  7924.  
  7925.        void rsc_gtrees(int treeindex, OBJECT **pptree, ...)
  7926.        ______________________________________________________________________
  7927.  
  7928.        Summary:  Retrieve the pointers to one or more dialog trees within the
  7929.                  resource data area.
  7930.  
  7931.        Input:    The treeindex parameter is the index of the tree.  This is
  7932.                  the name you assigned the tree in the resource editor.
  7933.  
  7934.                  The pptree parameter is a pointer to your tree pointer
  7935.                  variable (OBJECT * type).
  7936.  
  7937.                  The ... parameters are additional treeindex/pptree pairs. 
  7938.                  Use an index value of -1 to indicate the end of the
  7939.                  parameter list.
  7940.  
  7941.        Returns:  Nothing.
  7942.  
  7943.        See Also:
  7944.  
  7945.        Details:  This function simplifies the process of getting your
  7946.                  resource tree pointers.  Typically, your program contains an
  7947.                  init routine which has a series of rsrc_gaddr() calls.  This
  7948.                  function allows you to replace that series of calls with a
  7949.                  single call.  
  7950.  
  7951.        Example:  If your resource data contains 3 trees, you might use:
  7952.  
  7953.                      OBJECT *menu;
  7954.                      OBJECT *maindialog;
  7955.                      OBJECT *selectdialog;
  7956.  
  7957.                      prg_init()
  7958.                      {
  7959.                          appl_init();
  7960.                          if (!rsrc_load("myrsc.rsc")) {
  7961.                              // complain and die
  7962.                          }
  7963.                          rsc_gtrees(MENUTREE, &menu,
  7964.                                     MAINTREE, &maindialog,
  7965.                                     SELCTONE, &selectdialog,
  7966.                                     -1);
  7967.                          menu_bar(menu, TRUE);
  7968.                          // etc
  7969.                      }
  7970.  
  7971.        Source:   aesfuncs\rscgtree.c
  7972.  
  7973.  
  7974.  
  7975.  
  7976.  
  7977.  
  7978.  
  7979.  
  7980.        
  7981.        ======================================================================
  7982.        GemFast v1.8                                                  Page 116
  7983.  
  7984.  
  7985.  
  7986.  
  7987.  
  7988.  
  7989.  
  7990.  
  7991.        short rsc_rrbuttons(OBJECT *ptree)
  7992.        ______________________________________________________________________
  7993.  
  7994.        Summary:  Change all radio buttons in a dialog tree to display as
  7995.                  rounded-corner buttons.
  7996.  
  7997.        Input:    The ptree parameter is a pointer to the dialog tree to be
  7998.                  modified.
  7999.  
  8000.        Returns:  Zero for success, or a negative (TOS) error code.
  8001.  
  8002.        See Also: rsc_cubuttons()
  8003.  
  8004.        Details:  This function modifies the visual appearance of all radio
  8005.                  buttons in a dialog, transforming them to extended G_USERDEF
  8006.                  objects and supplying a custom drawing function which draws
  8007.                  radio buttons with rounded corners.  This gives the user
  8008.                  immediate visual cues as to which buttons are selection
  8009.                  (on/off) buttons and which are radio buttons.  The selection
  8010.                  buttons (not modified by this function) will display as
  8011.                  standard square-corner buttons, and radio buttons will have
  8012.                  rounded corners.
  8013.  
  8014.                  This function lets you use a standard GEM resource editor to
  8015.                  create dialogs using GEM buttons.  There are no restrictions
  8016.                  on the way you design your buttons.
  8017.  
  8018.                  This function allocates a block of memory to contain the
  8019.                  XUSERBLK structures that it attaches to the button objects. 
  8020.                  If the allocation fails, ENSMEM (-39) is returned.  It is
  8021.                  also possible to get a return value of -35 (no more handles)
  8022.                  if the VDI shared workstation can't be opened.
  8023.  
  8024.                  Each selection or radio button object in the dialog tree is
  8025.                  transformed into an extended G_USERDEF object.  The main
  8026.                  implication of this transformation is that the button's
  8027.                  string pointer is moved from the object's ob_spec field to
  8028.                  the XUSERBLK ob_spec field.  If you use rsc_gstrings()
  8029.                  and/or rsc_sstrings() as your sole access to the button's
  8030.                  string, you don't have to worry about this at all.
  8031.  
  8032.                  Other than the button string pointer, you can continue to
  8033.                  access the buttons in the usual way, directly accessing the
  8034.                  ob_flags and ob_state fields as needed.  In addition, you
  8035.                  can use the extended object type as you wish; this function
  8036.                  changes the lower 8 bits of the ob_type field to G_USERDEF,
  8037.                  but leaves the upper 8 bits alone.
  8038.  
  8039.                  I would like to recommend that you don't mix button styles
  8040.                  in the same application.  Pick one style, (GEM, CUA, or RR)
  8041.                  and use it for all your dialogs.
  8042.  
  8043.        Source:   aesfuncs\rsrrubtn.c
  8044.  
  8045.  
  8046.        
  8047.        ======================================================================
  8048.        GemFast v1.8                                                  Page 117
  8049.  
  8050.  
  8051.  
  8052.  
  8053.  
  8054.  
  8055.  
  8056.  
  8057.        void rsc_sstrings(OBJECT *ptree, int object, char *pstr, ...)
  8058.        ______________________________________________________________________
  8059.  
  8060.        Summary:  Set the string pointers for one or more string-related
  8061.                  objects in a dialog tree.
  8062.  
  8063.        Input:    The ptree parameter is a pointer to the dialog tree
  8064.                  containing the string-related objects.
  8065.  
  8066.                  The object parameter is the index of the first object for
  8067.                  which you want to set the string pointer.
  8068.  
  8069.                  The pstr parameter is a pointer to your string variable
  8070.                  (char [] or "" type).  This pointer is copied into the
  8071.                  string object's string pointer field (ob_spec, te_ptext,
  8072.                  etc).
  8073.  
  8074.                  The ... parameters are additional object/pstr pairs.  Use an
  8075.                  object number of -1 to indicate the end of the list.
  8076.  
  8077.        Returns:  Nothing.
  8078.  
  8079.        See Also: rsc_gstrings() obj_ppstring()
  8080.  
  8081.        Details:  This allows you to easily initialize string-related objects
  8082.                  in a dialog tree to point at strings defined within your
  8083.                  program.  The description of the obj_ppstring() function
  8084.                  contains details on what objects are string-related.
  8085.  
  8086.                  You must specify at least one object/pstr pair following the
  8087.                  tree pointer in the call.  You can specify any number of
  8088.                  pairs following the first one to retrieve the pointers for
  8089.                  more than one object with a single call.  Specify -1 for the
  8090.                  index following the last pair.  (There's no need to supply a
  8091.                  pointer to go with the -1 object index.)  
  8092.  
  8093.                  This function understands how to find the real string
  8094.                  pointer for each of string-related object type.  It copes
  8095.                  with the INDIRECT flag.  It understands extended G_USERDEF
  8096.                  objects, where ob_spec has been moved into the XUSERBLK.
  8097.  
  8098.                  This function attaches string data defined in your program
  8099.                  to string-related objects in your dialog trees.  This is
  8100.                  especially handy for editable text objects, because some
  8101.                  resource editors don't allocate enough space for the object
  8102.                  in the resource data.  If you define an editable text object
  8103.                  and supply a te_pvalid string that allows 20 chars of input,
  8104.                  but you define an initial string of "abc" for the field,
  8105.                  some resource editors will only allocate 3 bytes of resource
  8106.                  string space for the field.  When the user enters 20 chars
  8107.                  of data into the 3-byte field, other resource data gets
  8108.                  corrupted.  To avoid this, you can allocate a 20-byte
  8109.                  character array in your program, and use this function to
  8110.                  make the editable field's te_ptext pointer point at your
  8111.  
  8112.        
  8113.        ======================================================================
  8114.        GemFast v1.8                                                  Page 118
  8115.  
  8116.  
  8117.  
  8118.  
  8119.  
  8120.  
  8121.  
  8122.  
  8123.                  array instead of the 3-byte area in the resource data.
  8124.  
  8125.        Example:  To supply a local string constant for a G_STRING item, a
  8126.                  local character array for an editable item, and the text for
  8127.                  an icon, you might use code like this:
  8128.  
  8129.                      char editbuffer[20] = ""; // 20 bytes, starts empty
  8130.                      char iconname[] = "This is ICON #1"; // a silly name
  8131.           
  8132.                      void dial_init()
  8133.                      {
  8134.                          rsc_sstrings(mydialog, 
  8135.                                          EDITOBJ,  editbuffer,
  8136.                                          ICON1,    iconname,
  8137.                                          TITLESTR, "My dialog v1.1a",
  8138.                                          -1);
  8139.                      }
  8140.  
  8141.        Source:   aesfuncs\rscsstr.c
  8142.  
  8143.  
  8144.  
  8145.  
  8146.  
  8147.  
  8148.  
  8149.  
  8150.  
  8151.  
  8152.  
  8153.  
  8154.  
  8155.  
  8156.  
  8157.  
  8158.  
  8159.  
  8160.  
  8161.  
  8162.  
  8163.  
  8164.  
  8165.  
  8166.  
  8167.  
  8168.  
  8169.  
  8170.  
  8171.  
  8172.  
  8173.  
  8174.  
  8175.  
  8176.  
  8177.  
  8178.        
  8179.        ======================================================================
  8180.        GemFast v1.8                                                  Page 119
  8181.  
  8182.  
  8183.  
  8184.  
  8185.  
  8186.  
  8187.  
  8188.  
  8189.        void rsc_sxtypes(OBJECT *ptree, int object, int xtype, ...)
  8190.        ______________________________________________________________________
  8191.  
  8192.        Summary:  Sets the extended object type in one or more objects.
  8193.  
  8194.        Input:    The ptree parameter is a pointer to the tree which contains
  8195.                  the objects.
  8196.  
  8197.                  The object parameter is the index of the first object for
  8198.                  which you want to set the extended object type.
  8199.  
  8200.                  The xtype parameter is the extended object type (a value
  8201.                  between 0x00 and 0xFF) to be set in the object.
  8202.  
  8203.                  The ... parameters are additional object/xtype pairs.  Use
  8204.                  an object number of -1 to indicate the end of the list.
  8205.  
  8206.        Returns:  Nothing.
  8207.  
  8208.        See Also: obj_bmbuttons() obj_xtfind() 
  8209.  
  8210.        Details:  This function sets the extended object type field in one or
  8211.                  more objects within a tree.  Extended object types are
  8212.                  discussed under the obj_bmbuttons() and obj_xtfind()
  8213.                  functions.  
  8214.  
  8215.                  Some resource editor programs let you set the extended type
  8216.                  when you create the resource, others don't allow that.  Use
  8217.                  this function to set the extended type values during program
  8218.                  startup when you can't set them in the resource editor.
  8219.  
  8220.        Source:   aesfuncs\rscsxtyp.c
  8221.  
  8222.  
  8223.  
  8224.  
  8225.  
  8226.  
  8227.  
  8228.  
  8229.  
  8230.  
  8231.  
  8232.  
  8233.  
  8234.  
  8235.  
  8236.  
  8237.  
  8238.  
  8239.  
  8240.  
  8241.  
  8242.  
  8243.  
  8244.        
  8245.        ======================================================================
  8246.        GemFast v1.8                                                  Page 120
  8247.  
  8248.  
  8249.  
  8250.  
  8251.  
  8252.  
  8253.  
  8254.  
  8255.        void rsc_treefix(OBJECT *ptree)
  8256.        ______________________________________________________________________
  8257.  
  8258.        Summary:  Performs xywh fixup on all objects in a tree.
  8259.  
  8260.        Input:    The ptree parameter is a pointer to the tree which needs
  8261.                  resolution fixup.
  8262.  
  8263.        Returns:  Nothing.
  8264.  
  8265.        See Also:
  8266.  
  8267.        Details:  This function calls rsrc_obfix() for every object in the
  8268.                  tree.  It's just a shortcut for calling the GEM object fixup
  8269.                  for all objects in a tree, and does not provide any custom
  8270.                  resolution fixup, scaling, etc.
  8271.  
  8272.                  Use this function to do fixup on resource trees which are
  8273.                  embedded in your source code.  Do NOT use this function on
  8274.                  trees loaded via rsrc_load(), since that function
  8275.                  automatically applies resolution fixup as it loads the
  8276.                  resource data.
  8277.  
  8278.        Source:   aesfuncs\rsctrfix.c
  8279.  
  8280.  
  8281.  
  8282.  
  8283.  
  8284.  
  8285.  
  8286.  
  8287.  
  8288.  
  8289.  
  8290.  
  8291.  
  8292.  
  8293.  
  8294.  
  8295.  
  8296.  
  8297.  
  8298.  
  8299.  
  8300.  
  8301.  
  8302.  
  8303.  
  8304.  
  8305.  
  8306.  
  8307.  
  8308.  
  8309.  
  8310.        
  8311.        ======================================================================
  8312.        GemFast v1.8                                                  Page 121
  8313.  
  8314.  
  8315.  
  8316.  
  8317.  
  8318.  
  8319.  
  8320.  
  8321.        Window Library
  8322.  
  8323.  
  8324.                  The window library contains functions that work with windows
  8325.                  and window-related events.
  8326.  
  8327.  
  8328.  
  8329.  
  8330.  
  8331.  
  8332.  
  8333.  
  8334.  
  8335.  
  8336.  
  8337.  
  8338.  
  8339.  
  8340.  
  8341.  
  8342.  
  8343.  
  8344.  
  8345.  
  8346.  
  8347.  
  8348.  
  8349.  
  8350.  
  8351.  
  8352.  
  8353.  
  8354.  
  8355.  
  8356.  
  8357.  
  8358.  
  8359.  
  8360.  
  8361.  
  8362.  
  8363.  
  8364.  
  8365.  
  8366.  
  8367.  
  8368.  
  8369.  
  8370.  
  8371.  
  8372.  
  8373.  
  8374.  
  8375.  
  8376.        
  8377.        ======================================================================
  8378.        GemFast v1.8                                                  Page 122
  8379.  
  8380.  
  8381.  
  8382.  
  8383.  
  8384.  
  8385.  
  8386.  
  8387.        short wnd_top(void)
  8388.        ______________________________________________________________________
  8389.  
  8390.        Summary:  Obtain the handle of the current top window.
  8391.  
  8392.        Input:    Nothing.
  8393.  
  8394.        Returns:  The handle of the currently-topped window.
  8395.  
  8396.        See Also:
  8397.  
  8398.        Details:  This function is a shortcut call for wind_get(0,WF_TOP,...),
  8399.                  since querying the current top window handle is something
  8400.                  GEM programs seem to do a lot.
  8401.  
  8402.        Source:   aesutil.s\wndtop.s
  8403.                  aesutil.c\wndtop.c
  8404.  
  8405.  
  8406.  
  8407.  
  8408.  
  8409.  
  8410.  
  8411.  
  8412.  
  8413.  
  8414.  
  8415.  
  8416.  
  8417.  
  8418.  
  8419.  
  8420.  
  8421.  
  8422.  
  8423.  
  8424.  
  8425.  
  8426.  
  8427.  
  8428.  
  8429.  
  8430.  
  8431.  
  8432.  
  8433.  
  8434.  
  8435.  
  8436.  
  8437.  
  8438.  
  8439.  
  8440.  
  8441.  
  8442.        
  8443.        ======================================================================
  8444.        GemFast v1.8                                                  Page 123
  8445.  
  8446.  
  8447.  
  8448.  
  8449.  
  8450.  
  8451.  
  8452.  
  8453.        void wind_update(short flag)
  8454.        void wnd_update(short flag)
  8455.        ______________________________________________________________________
  8456.  
  8457.        Summary:  Set or unset the window or mouse update flag, with stacked
  8458.                  call logic.
  8459.  
  8460.        NOTE:     A macro in GEMFAST.H automatically remaps your wind_update()
  8461.                  calls to wnd_update().
  8462.  
  8463.        Input:    The flag parameter is any of the GEM-defined flags for
  8464.                  wind_update().  (BEG_UPDATE, END_UPDATE, BEG_MCTRL,
  8465.                  END_MCTRL).
  8466.  
  8467.        Returns:  Nothing.
  8468.  
  8469.        See Also:
  8470.  
  8471.        Details:  This function causes wind_update() calls to be handled like
  8472.                  hide/show mouse calls:  3 BEG_UPDATE calls will require 3
  8473.                  END_UPDATE calls; only the 3rd END_UPDATE actually gets
  8474.                  passed to GEM.
  8475.  
  8476.                  This type of functionality is required in blackbox library
  8477.                  routines (such as GemFast itself), where the library routine
  8478.                  can't know whether wind_update() has already been called by
  8479.                  the application or not.  GEM will consider a single
  8480.                  END_UPDATE call sufficient to cancel any number of preceding
  8481.                  BEG_UPDATE calls.  That could result in a library routine
  8482.                  accidentally releasing the update flag before the
  8483.                  application was ready for it.  
  8484.  
  8485.                  This function keeps separate internal counters for the
  8486.                  UPDATE and MCTRL flags; the counter is incremented on each
  8487.                  BEG_whatever call, and decremented on each END_whatever
  8488.                  call.  It only passes a BEG_whatever call through if that
  8489.                  counter is currently at zero.  When it sees an END_whatever
  8490.                  call, it decrements the counter, and passes the call through
  8491.                  to GEM only if the counter has dropped back to zero.
  8492.  
  8493.                  A macro in GEMFAST.H automatically routes your exiting
  8494.                  wind_update() calls through wnd_update().  This is required
  8495.                  because all calls must go through this routine for the
  8496.                  stacked BEG/END system to work.
  8497.  
  8498.        Source:   aesfuncs\wndupdat.c
  8499.  
  8500.  
  8501.  
  8502.  
  8503.  
  8504.  
  8505.  
  8506.  
  8507.  
  8508.        
  8509.        ======================================================================
  8510.        GemFast v1.8                                                  Page 124
  8511.  
  8512.  
  8513.  
  8514.  
  8515.  
  8516.  
  8517.  
  8518.  
  8519.        Extended Binding Functions
  8520.  
  8521.  
  8522.                  The extended binding functions provide an alternate calling
  8523.                  format for some of the standard GEM functions.  For the most
  8524.                  part, the alternate standard allows you to pass a pointer to
  8525.                  a structure in place of the discreet parms accepted by the
  8526.                  corresponding GEM function.  This has several advantages,
  8527.                  including smaller faster code at runtime, and easier-to-read
  8528.                  source code.
  8529.  
  8530.                  These functions are all portable to compilers that have
  8531.                  their own (non-GemFast) low-level bindings.  
  8532.  
  8533.                  I would like to recommend that you use the envx_multi()
  8534.                  function instead of evnt_multi() in all your programs.  Get
  8535.                  used to working with the XMULTI structure it uses.  To be
  8536.                  quite frank, it's looking more and more like you'll be
  8537.                  required to use it in GemFast v2.0.
  8538.  
  8539.  
  8540.  
  8541.  
  8542.  
  8543.  
  8544.  
  8545.  
  8546.  
  8547.  
  8548.  
  8549.  
  8550.  
  8551.  
  8552.  
  8553.  
  8554.  
  8555.  
  8556.  
  8557.  
  8558.  
  8559.  
  8560.  
  8561.  
  8562.  
  8563.  
  8564.  
  8565.  
  8566.  
  8567.  
  8568.  
  8569.  
  8570.  
  8571.  
  8572.  
  8573.  
  8574.        
  8575.        ======================================================================
  8576.        GemFast v1.8                                                  Page 125
  8577.  
  8578.  
  8579.  
  8580.  
  8581.  
  8582.  
  8583.  
  8584.  
  8585.        short evnx_multi(XMULTI *xm)
  8586.        ______________________________________________________________________
  8587.  
  8588.        Summary:  Call evnt_multi() passing just a single pointer.
  8589.  
  8590.        Input:    The xm parameter is a pointer to an XMULTI structure.
  8591.  
  8592.        Returns:  The mask of events which occurred; xm->mwhich.
  8593.  
  8594.        Details:  This function keeps all the input and output parms for an
  8595.                  evnt_multi() call in a single structure.  This is more
  8596.                  efficient than stacking and unstacking 50-some bytes of
  8597.                  parameters on each call, and it also allows you to "pass
  8598.                  off" event handling to a series of event handlers by passing
  8599.                  a single pointer to each handler.  GemFast 2.0 will make
  8600.                  heavy use of the latter technique.
  8601.  
  8602.                  The XMULTI structure is defined in GEMFAST.H, as follows:
  8603.  
  8604.                      typedef struct xmulti {
  8605.                          short   msgbuf[8];  /* Message buffer
  8606.                          short   mflags,     /* Mask of events to wait for */
  8607.                                  mbclicks,   /* Button clicks to wait for  */
  8608.                                  mbmask,     /* Which buttons to wait for  */
  8609.                                  mbstate,    /* Wait for button up/down    */
  8610.                                  mm1flags;   /* M1 event: wait for in/out  */
  8611.                          GRECT   mm1rect;    /* M1 event: coordinates      */
  8612.                          short   mm2flags;   /* M2 event: wait for in/out  */
  8613.                          GRECT   mm2rect;    /* M2 event: coordinates      */
  8614.                          long    mtcount;    /* Timer count (a longword!)  */
  8615.                          short   mwhich,     /* Bitmap of occurred events  */
  8616.                                  mmox,       /* Mouse x at time of event   */
  8617.                                  mmoy,       /* Mouse y at time of event   */
  8618.                                  mmobutton,  /* Mouse buttons at event     */
  8619.                                  mmokstate,  /* Keystate (shift) at event  */
  8620.                                  mkreturn,   /* Key pressed                */
  8621.                                  mbreturn;   /* Mouse button click count   */
  8622.                      } XMULTI;
  8623.  
  8624.                  You can use the values in the XMULTI structure just as you
  8625.                  would use discreet variables with an evnt_multi() call.  
  8626.  
  8627.                  I would like to caution against a technique I've seen in
  8628.                  some programs:  don't compare the return value (or xm.mwhich
  8629.                  field) using the equality operator.  This field holds a
  8630.                  bitmap of events that occurred, and GEM *will* return
  8631.                  multiple events at once in some situations.  You should test
  8632.                  for each event type you expect using the & operator.  
  8633.  
  8634.                  I would like to recommend that you get used to using this
  8635.                  function, because the overwhelming likelihood is that you'll
  8636.                  have to use it in GemFast 2.0 for the library to work right.
  8637.  
  8638.        Source:   gemfuncs\evnxmult.c
  8639.  
  8640.        
  8641.        ======================================================================
  8642.        GemFast v1.8                                                  Page 126
  8643.  
  8644.  
  8645.  
  8646.  
  8647.  
  8648.  
  8649.  
  8650.  
  8651.        short frmx_center(OBJECT *ptree, GRECT *prect)
  8652.        ______________________________________________________________________
  8653.  
  8654.        Summary:  Call form_center() passing a single pointer for the return
  8655.                  values.
  8656.  
  8657.        Input:    The ptree parameter is a pointer to the object tree to be
  8658.                  centered.
  8659.  
  8660.                  The prect parameter is a pointer to a GRECT structure into
  8661.                  which the on-screen sizes of the dialog are returned.
  8662.  
  8663.        Returns:  TRUE (1) always.
  8664.  
  8665.        See Also: frm_sizes() 
  8666.  
  8667.        Details:  This function allows you to pass a single pointer to an
  8668.                  output rectangle, instead of the four pointers required by
  8669.                  the standard form_center() function.
  8670.  
  8671.        Source:   gemfuncs\frmxcent.c
  8672.  
  8673.  
  8674.  
  8675.  
  8676.  
  8677.  
  8678.  
  8679.  
  8680.  
  8681.  
  8682.  
  8683.  
  8684.  
  8685.  
  8686.  
  8687.  
  8688.  
  8689.  
  8690.  
  8691.  
  8692.  
  8693.  
  8694.  
  8695.  
  8696.  
  8697.  
  8698.  
  8699.  
  8700.  
  8701.  
  8702.  
  8703.  
  8704.  
  8705.  
  8706.        
  8707.        ======================================================================
  8708.        GemFast v1.8                                                  Page 127
  8709.  
  8710.  
  8711.  
  8712.  
  8713.  
  8714.  
  8715.  
  8716.  
  8717.        short frmx_dial(short action, GRECT *little, GRECT *big)
  8718.        ______________________________________________________________________
  8719.  
  8720.        Summary:  Call form_dial() passing pointers to the little and big
  8721.                  rectangles.
  8722.  
  8723.        Input:    The action parameter is the GEM-defined action flag.
  8724.  
  8725.                  The little parameter is a pointer to the small-size
  8726.                  rectangle used with the FMD_GROW and FMD_SHRINK action
  8727.                  flags.  Must not be NULL, but may point to a rectangle
  8728.                  containing all zeros.
  8729.  
  8730.                  The big parameter is a pointer to the big-size rectangle;
  8731.                  the rectangle the dialog will occupy on-screen.  Must not be
  8732.                  NULL.
  8733.  
  8734.        Returns:  TRUE (1) always.
  8735.  
  8736.        See Also:
  8737.  
  8738.        Details:  This function allows you to call form_dial() passing just
  8739.                  pointers to the two rectangles instead of passing all eight
  8740.                  rectangle fields as discreet values.
  8741.  
  8742.        Source:   gemfuncs\frmxdial.c
  8743.  
  8744.  
  8745.  
  8746.  
  8747.  
  8748.  
  8749.  
  8750.  
  8751.  
  8752.  
  8753.  
  8754.  
  8755.  
  8756.  
  8757.  
  8758.  
  8759.  
  8760.  
  8761.  
  8762.  
  8763.  
  8764.  
  8765.  
  8766.  
  8767.  
  8768.  
  8769.  
  8770.  
  8771.  
  8772.        
  8773.        ======================================================================
  8774.        GemFast v1.8                                                  Page 128
  8775.  
  8776.  
  8777.  
  8778.  
  8779.  
  8780.  
  8781.  
  8782.  
  8783.        short grfx_dragbox(GRECT *startrect, GRECT *boundrect,
  8784.                           GRECT *endrect)
  8785.        ______________________________________________________________________
  8786.  
  8787.        Summary:  Call graf_dragbox() passing just rectangle pointers.
  8788.  
  8789.        Input:    The startrect parameter is a pointer to the starting
  8790.                  location for the dragbox.
  8791.  
  8792.                  The boundrect parameter is a pointer to the rectangle
  8793.                  defining the boundary in which the ending rectangle is
  8794.                  confined.
  8795.  
  8796.                  The endrect parameter is a pointer to the rectangle which
  8797.                  will receive the results after the call.  This may point to
  8798.                  the same rectangle as startrect without any problems.
  8799.  
  8800.        Returns:  Non-zero on success, or zero on failure (per GEM).
  8801.  
  8802.        See Also:
  8803.  
  8804.        Details:  This function allows you to pass rectangle pointers instead
  8805.                  of discrete parameters to graf_dragbox().  In the most
  8806.                  common usage, the startrect and endrect parameters will be
  8807.                  the same, so that the rectangle is 'moved' by the dragbox
  8808.                  operation.  The width and height will never be changed by
  8809.                  this function, only the x and y.  You can often use the
  8810.                  global desktop rectangle variable (&gl_rwdesk) as the
  8811.                  boundrect parameter.
  8812.  
  8813.        Source:   gemfuncs\grfxdrag.c
  8814.  
  8815.  
  8816.  
  8817.  
  8818.  
  8819.  
  8820.  
  8821.  
  8822.  
  8823.  
  8824.  
  8825.  
  8826.  
  8827.  
  8828.  
  8829.  
  8830.  
  8831.  
  8832.  
  8833.  
  8834.  
  8835.  
  8836.  
  8837.  
  8838.        
  8839.        ======================================================================
  8840.        GemFast v1.8                                                  Page 129
  8841.  
  8842.  
  8843.  
  8844.  
  8845.  
  8846.  
  8847.  
  8848.  
  8849.        short winx_calc(short type, short kind, GRECT inrect, GRECT *outrect)
  8850.        ______________________________________________________________________
  8851.  
  8852.        Summary:  Call wind_calc() passing a single pointer to the output.
  8853.  
  8854.        Input:    The type, kind, and inrect parameters are identical to the
  8855.                  corresponding wind_calc() parameters.
  8856.  
  8857.                  The outrect parameter is a pointer to the output rectangle
  8858.                  where the results of the calculation are stored.
  8859.  
  8860.        Returns:  Zero on error, or non-zero on success.
  8861.  
  8862.        See Also:
  8863.  
  8864.        Details:  Please note that the inrect parameter is a structure passed
  8865.                  by value (4 values stacked) not a pointer to a rectangle.
  8866.  
  8867.        Source:   gemfuncs\winxcalc.c
  8868.  
  8869.  
  8870.  
  8871.  
  8872.  
  8873.  
  8874.  
  8875.  
  8876.  
  8877.  
  8878.  
  8879.  
  8880.  
  8881.  
  8882.  
  8883.  
  8884.  
  8885.  
  8886.  
  8887.  
  8888.  
  8889.  
  8890.  
  8891.  
  8892.  
  8893.  
  8894.  
  8895.  
  8896.  
  8897.  
  8898.  
  8899.  
  8900.  
  8901.  
  8902.  
  8903.  
  8904.        
  8905.        ======================================================================
  8906.        GemFast v1.8                                                  Page 130
  8907.  
  8908.  
  8909.  
  8910.  
  8911.  
  8912.  
  8913.  
  8914.  
  8915.        short winx_get(short whandle, short field, GRECT *outrect)
  8916.        ______________________________________________________________________
  8917.  
  8918.        Summary:  Call wind_get() passing a single output pointer.
  8919.  
  8920.        Input:    The whandle and field parameters are identical to the
  8921.                  corresponding wind_get() parameters.
  8922.  
  8923.                  The outrect parameter is a pointer to the output rectangle
  8924.                  where the results of the query are stored.
  8925.  
  8926.        Returns:  Zero on error or non-zero on success.
  8927.  
  8928.        See Also:
  8929.  
  8930.        Details:  Please note that this function will always write 8 bytes of
  8931.                  output to the memory location indicated by outrect even if
  8932.                  the type of query you're doing normally returns less
  8933.                  information that.  (IE, don't use &integer_variable for this
  8934.                  parameter, or the memory following the integer variable will
  8935.                  be overwritten as well.)
  8936.  
  8937.        Source:   gemfuncs\winxget.c
  8938.  
  8939.  
  8940.  
  8941.  
  8942.  
  8943.  
  8944.  
  8945.  
  8946.  
  8947.  
  8948.  
  8949.  
  8950.  
  8951.  
  8952.  
  8953.  
  8954.  
  8955.  
  8956.  
  8957.  
  8958.  
  8959.  
  8960.  
  8961.  
  8962.  
  8963.  
  8964.  
  8965.  
  8966.  
  8967.  
  8968.  
  8969.  
  8970.        
  8971.        ======================================================================
  8972.        GemFast v1.8                                                  Page 131
  8973.  
  8974.  
  8975.  
  8976.  
  8977.  
  8978.  
  8979.  
  8980.  
  8981.        Extended VDI Functions
  8982.  
  8983.  
  8984.                  The extended VDI functions provide several functions not
  8985.                  documented in standard VDI reference manuals.
  8986.  
  8987.  
  8988.  
  8989.  
  8990.  
  8991.  
  8992.  
  8993.  
  8994.  
  8995.  
  8996.  
  8997.  
  8998.  
  8999.  
  9000.  
  9001.  
  9002.  
  9003.  
  9004.  
  9005.  
  9006.  
  9007.  
  9008.  
  9009.  
  9010.  
  9011.  
  9012.  
  9013.  
  9014.  
  9015.  
  9016.  
  9017.  
  9018.  
  9019.  
  9020.  
  9021.  
  9022.  
  9023.  
  9024.  
  9025.  
  9026.  
  9027.  
  9028.  
  9029.  
  9030.  
  9031.  
  9032.  
  9033.  
  9034.  
  9035.  
  9036.        
  9037.        ======================================================================
  9038.        GemFast v1.8                                                  Page 132
  9039.  
  9040.  
  9041.  
  9042.  
  9043.  
  9044.  
  9045.  
  9046.  
  9047.        short vdicall(short *control, short *intin, short *ptsin, 
  9048.                      short *intout, short *ptsout)
  9049.        ______________________________________________________________________
  9050.  
  9051.        Summary:  Direct call to VDI with caller-specified structures/arrays.
  9052.  
  9053.        Input:    All input parameters are pointers to arrays of int.  See
  9054.                  your VDI documentation for details on each of the arrays.
  9055.  
  9056.        Returns:  The contents of intout[0].
  9057.  
  9058.        Details:  This function allows you to call VDI functions not directly
  9059.                  supported by the VDIFAST.A library.  Within your program,
  9060.                  you set up arrays containing the parameters for the
  9061.                  function, and then pass pointers to those arrays to this
  9062.                  routine.  It will combine the pointers into a VDI parameter
  9063.                  block, and issue the VDI trap.
  9064.  
  9065.                  You must always supply a non-NULL pointer for control, and
  9066.                  the values in control must contain everything VDI needs to
  9067.                  process the call.  (IE, opcode, sub-opcode if needed, intin
  9068.                  count, ptsin count, and extended control info such as the
  9069.                  FDB pointers for a blit, if needed.)  You never need to
  9070.                  supply the intout or ptsout count values in the control
  9071.                  array; VDI will fill those in (and will ignore anything you
  9072.                  put there anyway).
  9073.  
  9074.                  The other array pointers may be NULL if they are not needed
  9075.                  for a given VDI call.  (If there are no ptsin parms for the
  9076.                  call, just code NULL for the ptsin parameter.)  The intout
  9077.                  array is handled specially: if you supply a NULL intout
  9078.                  pointer, the vdicall() routine allocates a 256-byte intout
  9079.                  array on the stack for you.  It returns the value from
  9080.                  intout[0] as the function return value, and discards the
  9081.                  rest of the array.  This is mainly to provide ease-of-use in
  9082.                  coding custom bindings which only need a single-word return
  9083.                  value.
  9084.  
  9085.        Source:   vdibind\vdicall.s
  9086.  
  9087.  
  9088.  
  9089.  
  9090.  
  9091.  
  9092.  
  9093.  
  9094.  
  9095.  
  9096.  
  9097.  
  9098.  
  9099.  
  9100.  
  9101.  
  9102.        
  9103.        ======================================================================
  9104.        GemFast v1.8                                                  Page 133
  9105.  
  9106.  
  9107.  
  9108.  
  9109.  
  9110.  
  9111.  
  9112.  
  9113.        long vgd_detect(void)
  9114.        long vg_gdos(void)
  9115.        ______________________________________________________________________
  9116.  
  9117.        Summary:  Detect presence of GDOS on system.
  9118.  
  9119.        Input:    None.
  9120.  
  9121.        Returns:  One of the following:
  9122.  
  9123.                      GDOS_NONE   - GDOS is not available.
  9124.                      GDOS_FNT    - 'Font GDOS' is available.
  9125.                      GDOS_FSM    - 'FSM' or 'Speedo' GDOS is available.
  9126.  
  9127.        Details:  The constants are defined in GEMFBIND.H or your compiler's
  9128.                  bindings header file.  The GDOS_NONE value is equal to zero.
  9129.  
  9130.        Source:   vdibind\vgdetect.s
  9131.  
  9132.  
  9133.  
  9134.  
  9135.  
  9136.  
  9137.  
  9138.  
  9139.  
  9140.  
  9141.  
  9142.  
  9143.  
  9144.  
  9145.  
  9146.  
  9147.  
  9148.  
  9149.  
  9150.  
  9151.  
  9152.  
  9153.  
  9154.  
  9155.  
  9156.  
  9157.  
  9158.  
  9159.  
  9160.  
  9161.  
  9162.  
  9163.  
  9164.  
  9165.  
  9166.  
  9167.  
  9168.        
  9169.        ======================================================================
  9170.        GemFast v1.8                                                  Page 134
  9171.  
  9172.  
  9173.  
  9174.  
  9175.  
  9176.  
  9177.  
  9178.  
  9179.        void v_gchar(short vdi_handle, short x, short y, char outchar)
  9180.        ______________________________________________________________________
  9181.  
  9182.        Summary:  Output a single character.
  9183.  
  9184.        Input:    The vdi_handle parameter is the handle of the VDI
  9185.                  workstation.
  9186.  
  9187.                  The x and y parameters are the coordinates at which the
  9188.                  character is placed.
  9189.  
  9190.                  The outchar parameter is the character to output.
  9191.  
  9192.        Returns:  Nothing.
  9193.  
  9194.        Details:  This function writes a single character to the screen.  It
  9195.                  requires less setup than the standard v_gtext() function,
  9196.                  and is a bit faster and easier to use.
  9197.  
  9198.                  This function is only available in the HSC and GNU versions
  9199.                  of GemFast.
  9200.  
  9201.        Source:   vdibind\vgchar.s
  9202.  
  9203.  
  9204.  
  9205.  
  9206.  
  9207.  
  9208.  
  9209.  
  9210.  
  9211.  
  9212.  
  9213.  
  9214.  
  9215.  
  9216.  
  9217.  
  9218.  
  9219.  
  9220.  
  9221.  
  9222.  
  9223.  
  9224.  
  9225.  
  9226.  
  9227.  
  9228.  
  9229.  
  9230.  
  9231.  
  9232.  
  9233.  
  9234.        
  9235.        ======================================================================
  9236.        GemFast v1.8                                                  Page 135
  9237.  
  9238.  
  9239.  
  9240.  
  9241.  
  9242.  
  9243.  
  9244.  
  9245.        Extended Object Library
  9246.  
  9247.  
  9248.                  The extended object library contains functions which
  9249.                  implement a set of new 'extended' objects, in effect
  9250.                  creating new types of objects not directly defined by GEM. 
  9251.                  It also contains functions for working with the new types of
  9252.                  objects (eg, setting or querying their current value.)
  9253.  
  9254.             Background
  9255.  
  9256.                  GEM defines a small variety of standard object types, such
  9257.                  as buttons, strings, text edit fields, boxes, etc.  GEM
  9258.                  programmers have long been creating dialog boxes that
  9259.                  contain related aggregates of these basic objects which work
  9260.                  together to give the appearance of a more complex object. 
  9261.                  The system file selector is a good example of this: a
  9262.                  collection of boxes, boxchars, and text objects work
  9263.                  together to give the appearance of a scrolling window within
  9264.                  the dialog box.
  9265.  
  9266.                  The only problem with the existing techniques is that
  9267.                  they're difficult to implement.  Every dialog that contains
  9268.                  one of these complex aggregate objects requires a custom
  9269.                  dialog handler function.  Coding just one such function can
  9270.                  take a week or more, and all that effort often leaves you
  9271.                  with an application-specific implementation of a single
  9272.                  dialog box which would then require even more work to use it
  9273.                  in other applications.
  9274.  
  9275.                  GemFast now supports a variety of pre-written extended
  9276.                  objects that you can easily use in your applications.  There
  9277.                  are two types of extended objects: passive and active.  
  9278.  
  9279.                  Passive objects just give a different visual appearance to a
  9280.                  standard GEM object, or define a new type of display-only
  9281.                  object, but there is no special action associated with
  9282.                  clicking on or otherwise manipulating the object.  They are
  9283.                  implemented with a standard G_USERDEF drawing routine, and
  9284.                  the standard GEM form_do() handler or any replacement dialog
  9285.                  handler can work with these objects.
  9286.  
  9287.                  Active objects are like mini-dialogs embedded within a
  9288.                  dialog.  They often consist of multiple objects working
  9289.                  together, but logically they take just one object slot in
  9290.                  your dialog tree.  These objects react to a mouse click on
  9291.                  their various components by using an object-specific custom
  9292.                  dialog handler invoked by frm_dialog().  For this reason,
  9293.                  the normal system form_do() handler and compatible
  9294.                  replacment handlers cannot be used with dialogs containing
  9295.                  active extended objects.  (The objects would be drawn
  9296.                  correctly, but would fail to behave properly without
  9297.                  frm_dialog() dispatching the custom handlers attached to the
  9298.                  object.)
  9299.  
  9300.        
  9301.        ======================================================================
  9302.        GemFast v1.8                                                  Page 136
  9303.  
  9304.  
  9305.  
  9306.  
  9307.  
  9308.  
  9309.  
  9310.  
  9311.  
  9312.             Using Extended Objects
  9313.  
  9314.                  Using extended objects is fairly simple.  A resource
  9315.                  construction program won't know anything about extended
  9316.                  objects, so when designing your dialog, G_BOX objects serve
  9317.                  as  placeholders for the extended objects.  The G_BOX
  9318.                  objects define the size and location of the extended object,
  9319.                  and effectively reserve a slot in the object tree array for
  9320.                  the extended object.  During program initialization, you
  9321.                  call a GemFast extended object library function to transform
  9322.                  the placeholder box into the desired type of extended
  9323.                  object.
  9324.  
  9325.                  Some extended objects impose minimum and maximum sizes for
  9326.                  the placeholder G_BOX object you design into your dialogs. 
  9327.                  These limits are documented in the create() function for
  9328.                  each object, and are expressed in terms of characters.  If
  9329.                  the routine lists the limit as None, that means that the
  9330.                  actual limit is the screen resolution.  The library routines
  9331.                  are resolution-independent, and fractional character
  9332.                  placements and sizes work fine.  (EG, if the minimum height
  9333.                  is 1 character for an object, you can design the dialog with
  9334.                  a placeholder box that is 1 character plus 4 pixels high,
  9335.                  but the usual problems of scaling objects at rsrc_load()
  9336.                  time will still occur, just as they would if the G_BOX
  9337.                  object wasn't transformed into an extended object.)
  9338.  
  9339.                  Once the transformation has been done, you just call
  9340.                  frm_dialog() as usual to process the dialog.  If the
  9341.                  extended object is an active type, frm_dialog() and the
  9342.                  extended object library functions work together to manage
  9343.                  interaction between the object and the user.  Control
  9344.                  doesn't return to your code until the user clicks on an exit
  9345.                  button in your dialog box.  (In some cases, a double-click
  9346.                  on a component within an extended object is equivalent to
  9347.                  clicking on the dialog's default exit button.  This is
  9348.                  analogous to double-clicking a file in the system file
  9349.                  selector: the double-click is the same as a single-click on
  9350.                  a filename followed by a click on the default OK button.)
  9351.  
  9352.                  Most extended objects have a value associated with them. 
  9353.                  For example, the numeric slider object represents a numeric
  9354.                  value; the text scroll list object has a currently-selected
  9355.                  string within the list, and so on.  The object library
  9356.                  functions obj_gvalue(), obj_svalue(), obj_gstring(), and
  9357.                  obj_string() can be used to get and set the values
  9358.                  associated with an extended object, just as they would be
  9359.                  used in getting/setting the values of standard GEM objects.
  9360.  
  9361.                  In some cases, there are multiple values associated with an
  9362.                  extended object.  For example, in a text scroll list object
  9363.                  there is the currently-selected string, the index of the
  9364.                  string currently at the top of the visible list, the number
  9365.  
  9366.        
  9367.        ======================================================================
  9368.        GemFast v1.8                                                  Page 137
  9369.  
  9370.  
  9371.  
  9372.  
  9373.  
  9374.  
  9375.  
  9376.  
  9377.                  of strings in the list, and so on.  In this case, the
  9378.                  extended object library provides functions to get and set
  9379.                  these related values, which are usually stored in hidden
  9380.                  data structures attached to the object.
  9381.  
  9382.                  If you look at the GemFast source code, you'll notice that
  9383.                  some extended object types have custom data structures
  9384.                  attached to them through the object ob_spec pointer. 
  9385.                  Sometimes these objects are a standard XUSERBLK structure,
  9386.                  sometimes they're custom structures that have an XUSERBLK as
  9387.                  the first field.  You must never access these structures
  9388.                  directly or make any assumptions about what they contain. 
  9389.                  If you do so, your programs will break with future releases
  9390.                  that have new library internals.  Use only the functions
  9391.                  defined in this document to access extended objects.
  9392.  
  9393.  
  9394.  
  9395.  
  9396.  
  9397.  
  9398.  
  9399.  
  9400.  
  9401.  
  9402.  
  9403.  
  9404.  
  9405.  
  9406.  
  9407.  
  9408.  
  9409.  
  9410.  
  9411.  
  9412.  
  9413.  
  9414.  
  9415.  
  9416.  
  9417.  
  9418.  
  9419.  
  9420.  
  9421.  
  9422.  
  9423.  
  9424.  
  9425.  
  9426.  
  9427.  
  9428.  
  9429.  
  9430.  
  9431.  
  9432.        
  9433.        ======================================================================
  9434.        GemFast v1.8                                                  Page 138
  9435.  
  9436.  
  9437.  
  9438.  
  9439.  
  9440.  
  9441.  
  9442.  
  9443.        void xob_nslide_change(OBJECT *tree, short object, 
  9444.                                  long newmin, long newmax)
  9445.        ______________________________________________________________________
  9446.  
  9447.        Summary:  Changes the range of numbers a numeric slider can represent.
  9448.  
  9449.        Input:    The ptree parameter is a pointer to the object tree
  9450.                  containing the G_NSLIDE object.
  9451.         
  9452.                  The object parameter is the index of the G_NSLIDE object.
  9453.  
  9454.                  The newmin parameter is the smallest number the slider can
  9455.                  be set to.
  9456.  
  9457.                  The newmax parameter is the largest number the slider can be
  9458.                  set to.
  9459.  
  9460.        Returns:  Nothing.
  9461.  
  9462.        See Also: xob_nslide_create() xob_nslide_get() xob_nslide_set()
  9463.  
  9464.        Details:  This function changes the range of numbers that the numeric
  9465.                  slider can be set to.  If the current value of the slider is
  9466.                  outside the new range, the value is clipped to either newmin
  9467.                  or newmax as appropriate.  This function does not update the
  9468.                  numeric slider on the screen.
  9469.  
  9470.        Source:   aesfuncs\xobnslid.c
  9471.  
  9472.  
  9473.  
  9474.  
  9475.  
  9476.  
  9477.  
  9478.  
  9479.  
  9480.  
  9481.  
  9482.  
  9483.  
  9484.  
  9485.  
  9486.  
  9487.  
  9488.  
  9489.  
  9490.  
  9491.  
  9492.  
  9493.  
  9494.  
  9495.  
  9496.  
  9497.  
  9498.        
  9499.        ======================================================================
  9500.        GemFast v1.8                                                  Page 139
  9501.  
  9502.  
  9503.  
  9504.  
  9505.  
  9506.  
  9507.  
  9508.  
  9509.        short xob_nslide_create(OBJECT *tree, short object, 
  9510.                                  long min, long max)
  9511.        ______________________________________________________________________
  9512.  
  9513.        Summary:  Creates a G_NSLIDE numeric slider data entry object.
  9514.  
  9515.        Input:    The ptree parameter is a pointer to the object tree
  9516.                  containing the object to be transformed.
  9517.         
  9518.                  The object parameter is the index of the object to be
  9519.                  transformed.
  9520.  
  9521.                  The min parameter is the smallest number the slider can be
  9522.                  set to.
  9523.  
  9524.                  The max parameter is the largest number the slider can be
  9525.                  set to.
  9526.  
  9527.        Returns:  Zero for success or a negative error code.
  9528.  
  9529.        See Also: xob_nslide_change() xob_nslide_get() xob_nslide_set()
  9530.  
  9531.        Details:  A G_NSLIDE is an active extended object.  It is used for
  9532.                  numeric input without requiring the user to type a number. 
  9533.                  Visually, the object resembles a window horizontal scroll
  9534.                  control, except that the sliding part of the scroller also
  9535.                  displays the current numeric value.  
  9536.  
  9537.                  The user can change the numeric value by clicking on the
  9538.                  left and right arrows to increment/decrement the current
  9539.                  value by one, or by clicking anywhere in the scroll area to
  9540.                  jump the scroller to that location, or by dragging the
  9541.                  scroller to the appropriate location in the scroll area. 
  9542.                  The numeric display in the scroller is constantly updated as
  9543.                  the user clicks or drags with the mouse.
  9544.  
  9545.                  The numeric slider occupies exactly the same location on-
  9546.                  screen as the G_BOX placeholder object would.  Size limits:
  9547.  
  9548.                      Minimum width:  5 characters
  9549.                      Maximum width:  None
  9550.                      Minimum height: 1 character
  9551.                      Maximum height: None (recommended max is 2 characters)
  9552.  
  9553.                  A wider object gives the user better control over the values
  9554.                  that result from dragging the slide bar, especially when the
  9555.                  range of possible values is large.
  9556.  
  9557.                  The xob_nslide_set() function can be used to set the current
  9558.                  value of the numeric slider without user interaction, and to
  9559.                  set the initial value after creating it.  By default, the
  9560.                  initial value is zero, or the min or max value if zero is
  9561.                  not within that range.
  9562.  
  9563.  
  9564.        
  9565.        ======================================================================
  9566.        GemFast v1.8                                                  Page 140
  9567.  
  9568.  
  9569.  
  9570.  
  9571.  
  9572.  
  9573.  
  9574.  
  9575.                  The xob_nslide_get() function can be used to get the current
  9576.                  value of the numeric slider.  The standard obj_gvalue() can
  9577.                  also be used to get the current value.
  9578.  
  9579.                  The xob_nslide_change() function can used to change the min
  9580.                  and/or max range limits after the object has been created.
  9581.  
  9582.        Source:   aesfuncs\xobnslid.c
  9583.  
  9584.  
  9585.  
  9586.  
  9587.  
  9588.  
  9589.  
  9590.  
  9591.  
  9592.  
  9593.  
  9594.  
  9595.  
  9596.  
  9597.  
  9598.  
  9599.  
  9600.  
  9601.  
  9602.  
  9603.  
  9604.  
  9605.  
  9606.  
  9607.  
  9608.  
  9609.  
  9610.  
  9611.  
  9612.  
  9613.  
  9614.  
  9615.  
  9616.  
  9617.  
  9618.  
  9619.  
  9620.  
  9621.  
  9622.  
  9623.  
  9624.  
  9625.  
  9626.  
  9627.  
  9628.  
  9629.  
  9630.        
  9631.        ======================================================================
  9632.        GemFast v1.8                                                  Page 141
  9633.  
  9634.  
  9635.  
  9636.  
  9637.  
  9638.  
  9639.  
  9640.  
  9641.        long xob_nslide_get(OBJECT *tree, short object)
  9642.        ______________________________________________________________________
  9643.  
  9644.        Summary:  Obtains the current value from a numeric slider object.
  9645.  
  9646.        Input:    The ptree parameter is a pointer to the object tree
  9647.                  containing the G_NSLIDE object.
  9648.         
  9649.                  The object parameter is the index of the G_NSLIDE object.
  9650.  
  9651.        Returns:  The current value displayed in the object.
  9652.  
  9653.        See Also: xob_nslide_create() xob_nslide_change() xob_nslide_set()
  9654.  
  9655.        Details:  This function obtains the current value being represented by
  9656.                  the numeric slider object.  The obj_gvalue() function can
  9657.                  also obtain a numeric slider's value.  
  9658.  
  9659.        Source:   aesfuncs\xobnslid.c
  9660.  
  9661.  
  9662.  
  9663.  
  9664.  
  9665.  
  9666.  
  9667.  
  9668.  
  9669.  
  9670.  
  9671.  
  9672.  
  9673.  
  9674.  
  9675.  
  9676.  
  9677.  
  9678.  
  9679.  
  9680.  
  9681.  
  9682.  
  9683.  
  9684.  
  9685.  
  9686.  
  9687.  
  9688.  
  9689.  
  9690.  
  9691.  
  9692.  
  9693.  
  9694.  
  9695.  
  9696.        
  9697.        ======================================================================
  9698.        GemFast v1.8                                                  Page 142
  9699.  
  9700.  
  9701.  
  9702.  
  9703.  
  9704.  
  9705.  
  9706.  
  9707.        void xob_nslide_set(OBJECT *tree, short object, long newvalue)
  9708.        ______________________________________________________________________
  9709.  
  9710.        Summary:  Sets a new value in a numeric slider object.
  9711.  
  9712.        Input:    The ptree parameter is a pointer to the object tree
  9713.                  containing the G_NSLIDE object.
  9714.         
  9715.                  The object parameter is the index of the G_NSLIDE object.
  9716.  
  9717.                  The newvalue parameter is the new numeric value for the
  9718.                  object.
  9719.  
  9720.        Returns:  Nothing.
  9721.  
  9722.        See Also: xob_nslide_create() xob_nslide_change() xob_nslide_get()
  9723.  
  9724.        Details:  This function sets a numeric slider object to a new value. 
  9725.                  It does not update the object on-screen.  The new value is
  9726.                  clipped to the range previously set for the object.  The
  9727.                  obj_svalue() function can also be used to set a new value,
  9728.                  but it would not perform the range enforcement clipping that
  9729.                  this function does; use obj_svalue() with care.
  9730.  
  9731.        Source:   aesfuncs\xobnslid.c
  9732.  
  9733.  
  9734.  
  9735.  
  9736.  
  9737.  
  9738.  
  9739.  
  9740.  
  9741.  
  9742.  
  9743.  
  9744.  
  9745.  
  9746.  
  9747.  
  9748.  
  9749.  
  9750.  
  9751.  
  9752.  
  9753.  
  9754.  
  9755.  
  9756.  
  9757.  
  9758.  
  9759.  
  9760.  
  9761.  
  9762.        
  9763.        ======================================================================
  9764.        GemFast v1.8                                                  Page 143
  9765.  
  9766.  
  9767.  
  9768.  
  9769.  
  9770.  
  9771.  
  9772.  
  9773.        short xob_thermo_change(OBJECT *ptree, short object, short increments)
  9774.        ______________________________________________________________________
  9775.  
  9776.        Summary:  Changes the number of increments allotted to a G_THERMO.
  9777.  
  9778.        Input:    The ptree parameter is a pointer to the object tree
  9779.                  containing the G_THERMO object.
  9780.         
  9781.                  The object parameter is the index of the G_THERMO object. 
  9782.  
  9783.                  The increments parameter is the number of increments or
  9784.                  'ticks' the thermometer will display.
  9785.  
  9786.        Returns:  Zero on success, or a negative error code.
  9787.  
  9788.        See Also: xob_thermo_update() xob_thermo_create()
  9789.  
  9790.        Details:  This function changes the number increments a G_THERMO
  9791.                  object can display.  It also resets the current increment
  9792.                  count to zero.  It does not redraw the object.  
  9793.  
  9794.                  Note that the object may change size as a result of this
  9795.                  call, but it will not exceed the dimensions of the original
  9796.                  object before it was transformed into a G_THERMO object. 
  9797.                  (See the description of xob_thermo_create() for details on
  9798.                  how the number of increments affects the size and position
  9799.                  of the resulting object on-screen.)
  9800.  
  9801.        Source:   aesfuncs\xobtherm.c
  9802.  
  9803.  
  9804.  
  9805.  
  9806.  
  9807.  
  9808.  
  9809.  
  9810.  
  9811.  
  9812.  
  9813.  
  9814.  
  9815.  
  9816.  
  9817.  
  9818.  
  9819.  
  9820.  
  9821.  
  9822.  
  9823.  
  9824.  
  9825.  
  9826.  
  9827.  
  9828.        
  9829.        ======================================================================
  9830.        GemFast v1.8                                                  Page 144
  9831.  
  9832.  
  9833.  
  9834.  
  9835.  
  9836.  
  9837.  
  9838.  
  9839.        short xob_thermo_create(OBJECT *ptree, short object, short increments)
  9840.        ______________________________________________________________________
  9841.  
  9842.        Summary:  Creates a G_THERMO progress display object.
  9843.  
  9844.        Input:    The ptree parameter is a pointer to the object tree
  9845.                  containing the object to be transformed.
  9846.         
  9847.                  The object parameter is the index of the G_BOX object to be
  9848.                  transformed.
  9849.  
  9850.                  The increments parameter is the number of increments or
  9851.                  'ticks' the thermometer will display.
  9852.  
  9853.        Returns:  Zero on success, or a negative error code.
  9854.  
  9855.        See Also: xob_thermo_update() xob_thermo_change() frm_progress()
  9856.  
  9857.        Details:  A G_THERMO is a passive extended object.  The object is used
  9858.                  to indicate progress by incrementally filling the object
  9859.                  interior as progress is made.  The interior of the object is
  9860.                  always filled from left to right as progress increments are
  9861.                  made.  There is no way to implement vertical or right to
  9862.                  left progress.
  9863.  
  9864.                  Use xob_thermo_update() to increment the filled portion of
  9865.                  the object and optionally update the object on-screen.  Use
  9866.                  xob_thermo_change() to change the number of increments the
  9867.                  object can display after it has been created.
  9868.  
  9869.                  The G_THERMO object appears on-screen based on the size and
  9870.                  location of the G_BOX placeholder object, but it may not
  9871.                  occupy all the space of the original object, as described
  9872.                  below.  The fill pattern in your original G_BOX object is
  9873.                  used as the fill pattern for the G_THERMO.  You cannot
  9874.                  change the fill pattern once the object is transformed. 
  9875.                  Size limits:
  9876.  
  9877.                      Minimum width:  increments pixels
  9878.                      Maximum width:  None
  9879.                      Minimum height: 1 character
  9880.                      Maximum height: None (recommended max is 2 characters)
  9881.  
  9882.                  The increments parameter indicates how many increments the
  9883.                  thermo bar is capable of.  Based on the increments, the
  9884.                  G_THERMO object is sized in the horizontal dimension and
  9885.                  centered it within its original horizontal location.  The
  9886.                  resizing ensures that the total width is a multiple of the
  9887.                  number of increments that you requested.  For example, if
  9888.                  your original G_BOX was 210 pixels wide, and you request 100
  9889.                  increments in the G_THERMO, then the object will be 200
  9890.                  pixels wide, and each time you increment the progress
  9891.                  display, it will add 2 pixels of shading to the interior. 
  9892.                  Because the actual object is 10 pixels smaller than the
  9893.  
  9894.        
  9895.        ======================================================================
  9896.        GemFast v1.8                                                  Page 145
  9897.  
  9898.  
  9899.  
  9900.  
  9901.  
  9902.  
  9903.  
  9904.  
  9905.                  original box, it is displayed at an X offset 5 pixels to the
  9906.                  right of the original object (ie, centered within the space
  9907.                  the original object occupied).
  9908.  
  9909.                  Do not specify more increments than the width of the
  9910.                  original G_BOX object; it would result in an increment width
  9911.                  of zero pixels per tick.  If you do so, this function
  9912.                  returns -64 (range error), and doesn't transform the object.
  9913.  
  9914.                  See the xob_thermo_update() function for an example of using
  9915.                  xob_thermo_create().
  9916.  
  9917.        Source:   aesfuncs\xobtherm.c
  9918.  
  9919.  
  9920.  
  9921.  
  9922.  
  9923.  
  9924.  
  9925.  
  9926.  
  9927.  
  9928.  
  9929.  
  9930.  
  9931.  
  9932.  
  9933.  
  9934.  
  9935.  
  9936.  
  9937.  
  9938.  
  9939.  
  9940.  
  9941.  
  9942.  
  9943.  
  9944.  
  9945.  
  9946.  
  9947.  
  9948.  
  9949.  
  9950.  
  9951.  
  9952.  
  9953.  
  9954.  
  9955.  
  9956.  
  9957.  
  9958.  
  9959.  
  9960.        
  9961.        ======================================================================
  9962.        GemFast v1.8                                                  Page 146
  9963.  
  9964.  
  9965.  
  9966.  
  9967.  
  9968.  
  9969.  
  9970.  
  9971.        short xob_thermo_update(OBJECT *ptree, short object, short increments,
  9972.                                GRECT *pcliprect)
  9973.        ______________________________________________________________________
  9974.  
  9975.        Summary:  Update the increment count on a G_THERMO object, with
  9976.                  optional redraw.
  9977.  
  9978.        Input:    The ptree parameter is a pointer to the tree.
  9979.  
  9980.                  The object parameter is the index of the G_THERMO object.
  9981.  
  9982.                  The increments parameter is the new increment count for the
  9983.                  object, or one of the following special values:
  9984.  
  9985.                    OBJ_TINCREMENT -  Add one to the current increment count.
  9986.                    OBJ_TINQUIRE   -  Return current increment count without
  9987.                                      changing it.
  9988.  
  9989.                  The pcliprect parameter, if non-NULL, specifies the clipping
  9990.                  rectangle for the redraw.  If NULL, no redraw is done.  If
  9991.                  you need no clipping but want a redraw, pass &gl_rwdesk.
  9992.  
  9993.        Returns:  The increment count that was current before the call.
  9994.  
  9995.        See Also: xob_thermo_create()
  9996.  
  9997.        Details:  This function updates the increment count on a G_THERMO
  9998.                  object, and optionally redraws the object using the new
  9999.                  count.
  10000.  
  10001.                  If increments is zero or greater, the G_THERMO increment
  10002.                  count is set to increments.  If it is OBJ_TINCREMENT, this
  10003.                  function adds one to the current count.  The increment count
  10004.                  is clipped to the maximum number of increments set when the
  10005.                  G_THERMO was created or modified by xob_thermo_create().
  10006.  
  10007.                  In general, the OBJ_TINCREMENT (increment by one tick) value
  10008.                  should be the most common value passed for increments. 
  10009.                  Another useful technique is to create the G_THERMO with 100
  10010.                  increments and pass successive increments values that
  10011.                  represent current percentage of completion of the task.
  10012.  
  10013.                  If you pass a NULL pointer for a clipping rectangle, the
  10014.                  G_THERMO increment count is updated internally, but the
  10015.                  object is not updated on the screen.  This can be handy for
  10016.                  zeroing the increment count before displaying the dialog. 
  10017.  
  10018.  
  10019.  
  10020.  
  10021.  
  10022.  
  10023.  
  10024.  
  10025.  
  10026.        
  10027.        ======================================================================
  10028.        GemFast v1.8                                                  Page 147
  10029.  
  10030.  
  10031.  
  10032.  
  10033.  
  10034.  
  10035.  
  10036.  
  10037.        Example:  To report progress (using your own custom dialog box) as you
  10038.                  do something to each track of a floppy disk, you might use
  10039.                  code such as the following:
  10040.  
  10041.                      OBJECT  *pdialog;
  10042.  
  10043.                      rsc_gtrees(PROGRESS, &pdialog, -1);
  10044.                      if (!xob_thermo_create(pdialog, THERMOBAR, numtracks))
  10045.                          complain_and_die();
  10046.                      frm_dial(FRM_DSTART|FRM_DDRAW, pdialog, 0);
  10047.                      for (i = 0; i < numtracks; ++i) {
  10048.                          do_something_to_disk_track(i);
  10049.                          xob_thermo_update(pdialog, THERMOBAR, 
  10050.                                            OBJ_TINCREMENT, &gl_rwdesk);
  10051.                      }
  10052.                      frm_dialog(FRM_DFINISH, pdialog, 0);
  10053.  
  10054.        Source:   aesfuncs\xobtherm.c
  10055.  
  10056.  
  10057.  
  10058.  
  10059.  
  10060.  
  10061.  
  10062.  
  10063.  
  10064.  
  10065.  
  10066.  
  10067.  
  10068.  
  10069.  
  10070.  
  10071.  
  10072.  
  10073.  
  10074.  
  10075.  
  10076.  
  10077.  
  10078.  
  10079.  
  10080.  
  10081.  
  10082.  
  10083.  
  10084.  
  10085.  
  10086.  
  10087.  
  10088.  
  10089.  
  10090.  
  10091.  
  10092.        
  10093.        ======================================================================
  10094.        GemFast v1.8                                                  Page 148
  10095.  
  10096.  
  10097.  
  10098.  
  10099.  
  10100.  
  10101.  
  10102.  
  10103.        short xob_tscroll_create(OBJECT *ptree, short object, short statusobj)
  10104.        ______________________________________________________________________
  10105.  
  10106.        Summary:  Transform an object into a G_TSCROLL text list object.
  10107.  
  10108.        Input:    The ptree parameter is a pointer to the tree.
  10109.  
  10110.                  The object parameter is the index of the object to be
  10111.                  transformed.
  10112.  
  10113.                  The statusobj parameter is the index of another string-
  10114.                  related object in the same tree which reflects the current
  10115.                  selection in text scroll list.
  10116.  
  10117.        Returns:  Zero for success, or a negative error code.
  10118.  
  10119.        See Also: xob_tscroll_set() xob_tscroll_get()
  10120.  
  10121.        Details:  A G_TSCROLL is an active extended object.  It presents a
  10122.                  list of strings in a scrollable text 'window' object, and
  10123.                  allows the user to scroll through the list and/or select one
  10124.                  of the strings.  
  10125.  
  10126.                  The currently-selected string appears in reverse video, just
  10127.                  as a SELECTED object would appear in a dialog.  In addition,
  10128.                  if a status object is specified at creation time, the
  10129.                  currently selected string is updated into the status object
  10130.                  whenever the user makes a selection from the scrolling list
  10131.                  of strings.  The status object can be any string-related
  10132.                  object, including G_STRING, G_TEXT, G_BOXTEXT, etc.
  10133.  
  10134.                  The G_TSCROLL object occupies exactly the same screen area
  10135.                  as the original G_BOX placeholder object.  Size limits:
  10136.  
  10137.                      Minimum width:  10 characters
  10138.                      Maximum width:  None
  10139.                      Minimum height: 7 characters
  10140.                      Maximum height: 18 characters
  10141.  
  10142.                  The string data occupies only a portion of the G_TSCROLL
  10143.                  object; whitespace gutters and the scroll controls occupy
  10144.                  the remaining space.  The scroll controls and whitespace
  10145.                  occupy five character widths horizontally, and whitespace
  10146.                  occupies 2 character heights vertically.  Thus, you must
  10147.                  size the G_BOX placeholder object 5 characters wider than
  10148.                  the width of the strings you want to display, and 2
  10149.                  characters higher than the number of lines you want to
  10150.                  display.  If any of the displayed strings are wider than the
  10151.                  data area of the G_TSCROLL object, they are automatically
  10152.                  clipped to the data area.
  10153.  
  10154.                  Zero or more strings can be displayed with the G_TSCROLL
  10155.                  object.  If there are more strings than there are lines
  10156.                  available in the data window, the user can scroll through
  10157.  
  10158.        
  10159.        ======================================================================
  10160.        GemFast v1.8                                                  Page 149
  10161.  
  10162.  
  10163.  
  10164.  
  10165.  
  10166.  
  10167.  
  10168.  
  10169.                  the list of strings using what appear to be standard window
  10170.                  scroll controls.  The scrolling differs from a standard
  10171.                  window, however, in that the list scrolls as the slider bar
  10172.                  is dragged.
  10173.  
  10174.                  If the user clicks on a string in the data area, that string
  10175.                  becomes the currently-selected item.  If the user double-
  10176.                  clicks on a string in the data area, that string becomes the
  10177.                  currently-selected item, and the frm_dialog() function
  10178.                  driving the user interaction returns the index of the
  10179.                  dialog's default exit button.  For this reason, the 'Okay'
  10180.                  or other positive-action exit button for the dialog should
  10181.                  always be marked as the default exit object.  (If the dialog
  10182.                  doesn't have a default exit button, a double-click on a
  10183.                  string is the same as a single-click.)
  10184.  
  10185.                  The obj_gstring() function will return a pointer to the
  10186.                  currently-selected string within a G_TSCROLL object.  The
  10187.                  xob_tscroll_get() function returns the pointer, as well as
  10188.                  the index of the currently-selected string, and the index of
  10189.                  the string currently at the top of the data window.  If no
  10190.                  string is currently-selected, a NULL pointer is returned for
  10191.                  the string pointer, and NO_OBJECT is returned for the index.
  10192.  
  10193.                  The xob_tscroll_set() function is used to attach the list of
  10194.                  strings to the object, and to set other parameters that
  10195.                  affect the object.  Until a list of strings is attached to
  10196.                  the object, the data window appears empty.  The list of
  10197.                  strings is in the form of an array of pointers to the
  10198.                  strings; this is detailed under xob_tscroll_set().
  10199.  
  10200.        Source:   aesfuncs\xobtscro.c
  10201.  
  10202.  
  10203.  
  10204.  
  10205.  
  10206.  
  10207.  
  10208.  
  10209.  
  10210.  
  10211.  
  10212.  
  10213.  
  10214.  
  10215.  
  10216.  
  10217.  
  10218.  
  10219.  
  10220.  
  10221.  
  10222.  
  10223.  
  10224.        
  10225.        ======================================================================
  10226.        GemFast v1.8                                                  Page 150
  10227.  
  10228.  
  10229.  
  10230.  
  10231.  
  10232.  
  10233.  
  10234.  
  10235.        short xob_tscroll_get(OBJECT *ptree, short object, char **curstring,
  10236.                              short *curindex, short *topindex)
  10237.        ______________________________________________________________________
  10238.  
  10239.        Summary:  Obtains information about the state of a G_TSCROLL object.
  10240.  
  10241.        Input:    The ptree parameter is a pointer to the tree.
  10242.  
  10243.                  The object parameter is the index of the object to be
  10244.                  transformed.
  10245.  
  10246.                  The curstring parameter, if non-NULL, is used to return a
  10247.                  pointer to the currently-selected string.
  10248.  
  10249.                  The curindex parameter, if non-NULL, is used to return the
  10250.                  index of the currently-selected string.
  10251.  
  10252.                  The topindex parameter, if non-NULL, is used to return the
  10253.                  index of the line currently shown at the top of the window.
  10254.  
  10255.        Returns:  The index of the currently-selected string, or NO_OBJECT if
  10256.                  no string is selected.
  10257.  
  10258.        See Also: xob_tscroll_create() xob_tscroll_set() obj_gstring()
  10259.  
  10260.        Details:  This function returns information about the current state of
  10261.                  a G_TSCROLL object.  If you need only a pointer to the
  10262.                  currently-selected string, use obj_gstring().
  10263.  
  10264.                  If no string is currently selected, NO_OBJECT is returned
  10265.                  into *curindex and as the return value of the function, and
  10266.                  a NULL pointer is returned into *curstring.
  10267.  
  10268.                  Any or all of the returned-value pointers can be NULL to
  10269.                  indicate that you don't want that item of information.
  10270.  
  10271.        Source:   aesfuncs\xobtscro.c
  10272.  
  10273.  
  10274.  
  10275.  
  10276.  
  10277.  
  10278.  
  10279.  
  10280.  
  10281.  
  10282.  
  10283.  
  10284.  
  10285.  
  10286.  
  10287.  
  10288.  
  10289.  
  10290.        
  10291.        ======================================================================
  10292.        GemFast v1.8                                                  Page 151
  10293.  
  10294.  
  10295.  
  10296.  
  10297.  
  10298.  
  10299.  
  10300.  
  10301.        void xob_tscroll_set(OBJECT *ptree, short object, char **datalist,
  10302.                              short numlines, short curindex, short topindex)
  10303.        ______________________________________________________________________
  10304.  
  10305.        Summary:  Sets new values into a G_TSCROLL object.
  10306.  
  10307.        Input:    The ptree parameter is a pointer to the tree.
  10308.  
  10309.                  The object parameter is the index of the object to be
  10310.                  transformed.
  10311.  
  10312.                  The datalist parameter is a pointer to an array of string
  10313.                  pointers; the list of strings displayed by the object.
  10314.  
  10315.                  The numlines parameter is the number of lines in the string
  10316.                  list.
  10317.  
  10318.                  The curindex parameter is the index of the string which is
  10319.                  to be considered currently-selected.
  10320.  
  10321.                  The topindex parameter is the index of the string which is
  10322.                  to appear as the top line in the data window.
  10323.  
  10324.        Returns:  Nothing.
  10325.  
  10326.        See Also: xob_tscroll_create() xob_tscroll_get()
  10327.  
  10328.        Details:  This function changes the state of a G_TSCROLL object.  Use
  10329.                  it to attach a list of strings to an object, or to change
  10330.                  the state of the list currently attached to the object. 
  10331.                  This function does not update the object on-screen.  If a
  10332.                  change is made to the currently-selected item, and a status
  10333.                  object was associated with the G_TSCROLL at creation time,
  10334.                  the new selected string pointer is set into the status
  10335.                  object, but the status object is not updated on-screen.
  10336.  
  10337.                  The list of strings has the form of an array of pointers to
  10338.                  the strings.  If the last pointer in the array is NULL, you
  10339.                  can pass -1 for the numlines parameter, and this function
  10340.                  will count the number of strings internally.  If the last
  10341.                  pointer in the array is not NULL, you must pass a positive
  10342.                  value for numlines when you attach a new string list. 
  10343.  
  10344.                  The parameters interact with each other depending on the
  10345.                  values you pass, as described below.  Despite the arcane
  10346.                  interactions possible between the parameters, the most
  10347.                  common use of this function is to attach an initial or new
  10348.                  list of strings.  In this context, usage is fairly simple;
  10349.                  pass a non-NULL datalist pointer, and -1 for all the other
  10350.                  parameters.  This attaches the list, automatically counts
  10351.                  the lines in the list, sets the data window to display the
  10352.                  first list line at the top of the window, and starts with no
  10353.                  string initially selected.  If the dialog containing the
  10354.                  list is used multiple times after doing this, and the
  10355.  
  10356.        
  10357.        ======================================================================
  10358.        GemFast v1.8                                                  Page 152
  10359.  
  10360.  
  10361.  
  10362.  
  10363.  
  10364.  
  10365.  
  10366.  
  10367.                  contents of the list haven't been changed by other actions
  10368.                  of your program, the user will always see the list in the
  10369.                  same state as the last time it was visible.  If something
  10370.                  done by your program does cause the list contents to change
  10371.                  between calls, just use the datalist, -1, -1, -1 sequence
  10372.                  again to attach the new list (or make the object see the
  10373.                  changes in the existing list).
  10374.  
  10375.                  If the datalist parameter is NULL, the existing list of
  10376.                  strings remains attached to the object.  If non-NULL, a new
  10377.                  list of strings is attached to the object.  If curindex is
  10378.                  not also specified, no string from the new list is
  10379.                  considered currently-selected.  If the topindex parameter is
  10380.                  not also specified, the first line of the new list is
  10381.                  displayed at the top of the data window.
  10382.  
  10383.                  The numlines parameter is the number of lines in the list. 
  10384.                  This parameter may be zero, indicating that the list is
  10385.                  empty.  If you pass -1 and a non-NULL datalist parameter,
  10386.                  the strings in the datalist are counted automatically.  If
  10387.                  you pass -1 and the datalist parameter is NULL, that
  10388.                  indicates that you are making no change to the number of
  10389.                  lines in the list already attached to the object.  For ease-
  10390.                  of-use, it is best to always place a NULL pointer at the end
  10391.                  of the string list, and always pass -1 for numlines.  Doing
  10392.                  this will ensure that the internal line count changes only
  10393.                  when you attach a new list to the object (ie, the datalist
  10394.                  parameter becomes the controlling factor, and you never need
  10395.                  to worry about numlines).
  10396.  
  10397.                  The curindex parameter, if greater than or equal to zero,
  10398.                  sets a given string in the list to currently-selected
  10399.                  status.  It can be used with a non-NULL datalist parameter
  10400.                  to preselect a string from the new list, or with a NULL
  10401.                  datalist parameter to force the given string to currently-
  10402.                  selected status.  If -1 is passed, no change is made to the
  10403.                  currently-selected string.  If the value passed is greater
  10404.                  than or equal to the number of lines in the list, it
  10405.                  deselects any currently-selected string.  Thus, a parameter
  10406.                  sequence of NULL, -1, 32767, -1 effectively deselects any
  10407.                  currently-selected string without affecting other attributes
  10408.                  of the object.
  10409.  
  10410.                  The topindex parameter, if greater than or equal to zero,
  10411.                  sets a given string as the one to be displayed as the top
  10412.                  line in the window.  If -1 is passed, no change is made to
  10413.                  the current top display line.  If the value passed is
  10414.                  greater than or equal to the number of lines in the list,
  10415.                  the display is aligned to the last page of data in the list.
  10416.  
  10417.                  Passing positive values for curindex and topindex is useful
  10418.                  primarily when, for example, you store a string list and the
  10419.                  currently-selected string in a configuration file, and wish
  10420.                  to load the configuration from a prior run of the program
  10421.  
  10422.        
  10423.        ======================================================================
  10424.        GemFast v1.8                                                  Page 153
  10425.  
  10426.  
  10427.  
  10428.  
  10429.  
  10430.  
  10431.  
  10432.  
  10433.                  into the object.  
  10434.  
  10435.                  If a positive numlines parameter is passed, and it doesn't
  10436.                  accurately reflect the count of lines in the list, Bad
  10437.                  Things will happen when you try display/use the list.  If
  10438.                  positive curindex or topindex values are passed which are
  10439.                  out of range, this function basically forces them back into
  10440.                  range.  
  10441.  
  10442.        Source:   aesfuncs\xobtscro.c
  10443.  
  10444.  
  10445.  
  10446.  
  10447.  
  10448.  
  10449.  
  10450.  
  10451.  
  10452.  
  10453.  
  10454.  
  10455.  
  10456.  
  10457.  
  10458.  
  10459.  
  10460.  
  10461.  
  10462.  
  10463.  
  10464.  
  10465.  
  10466.  
  10467.  
  10468.  
  10469.  
  10470.  
  10471.  
  10472.  
  10473.  
  10474.  
  10475.  
  10476.  
  10477.  
  10478.  
  10479.  
  10480.  
  10481.  
  10482.  
  10483.  
  10484.  
  10485.  
  10486.  
  10487.  
  10488.        
  10489.        ======================================================================
  10490.        GemFast v1.8                                                  Page 154
  10491.  
  10492.  
  10493.  
  10494.  
  10495.  
  10496.  
  10497.  
  10498.  
  10499.        Extended Object Developer's Guide
  10500.  
  10501.  
  10502.                  Beta testers note:  this chapter is not complete, and
  10503.                  anything you read here might be inaccurate.
  10504.  
  10505.                  Starting with GemFast v1.9, a support infrastructure for
  10506.                  extended objects is coming into being.  Extended objects are
  10507.                  currently the major area of growth within GemFast.  While I
  10508.                  encourage everyone with any interest to code new extended
  10509.                  objects using this infrastructure, and send me the results
  10510.                  for inclusion in future releases, I do so with caveats:
  10511.  
  10512.                    - It takes a fairly advanced knowledge of C and object-
  10513.                      oriented techniques coded in C to understand and use the
  10514.                      growing infrastructure of support.
  10515.  
  10516.                    - The infrastructure probably isn't complete, and Big
  10517.                      Changes could be required in your internals, or even be
  10518.                      suggested by you to support your objects.
  10519.  
  10520.                    - As more of these objects come into being, we're going to
  10521.                      find common chunks of code showing up in all of them,
  10522.                      and this will lead to the creation of more common
  10523.                      support routines that are shared by many objects.  But I
  10524.                      haven't yet attempted to pre-design such items,
  10525.                      preferring to let the process drive the design instead
  10526.                      of having a half-thought-out design limit the process.
  10527.                   
  10528.                    - The forms library needs to be extended a bit to allow
  10529.                      replacement form_do() handlers, and provisions need to
  10530.                      be made for those handlers to be able to cope with
  10531.                      extended objects.  In particular, we need a way to feed
  10532.                      keystrokes to extended objects through the ub_touch
  10533.                      vector.
  10534.  
  10535.                  (Need a lot more words here.)
  10536.  
  10537.  
  10538.  
  10539.  
  10540.  
  10541.  
  10542.  
  10543.  
  10544.  
  10545.  
  10546.  
  10547.  
  10548.  
  10549.  
  10550.  
  10551.  
  10552.  
  10553.  
  10554.        
  10555.        ======================================================================
  10556.        GemFast v1.8                                                  Page 155
  10557.  
  10558.  
  10559.  
  10560.  
  10561.  
  10562.  
  10563.  
  10564.  
  10565.        void xob_draw(OBJECT *ptree, short object, short depth,
  10566.                      GRECT *cliprect)
  10567.        ______________________________________________________________________
  10568.  
  10569.        Summary:  Object drawing module callable from supervisor mode.
  10570.  
  10571.        Input:    The ptree parameter is a pointer to the object tree to be
  10572.                  drawn.
  10573.  
  10574.                  The object parameter is the index of the object to start
  10575.                  drawing at.
  10576.  
  10577.                  The depth parameter is the number of levels of children of
  10578.                  the starting object which are to be drawn.
  10579.  
  10580.                  The cliprect parameter is a pointer to the clipping
  10581.                  rectangle for the drawing.
  10582.  
  10583.        Returns:  Nothing.
  10584.  
  10585.        See Also:
  10586.  
  10587.        Details:  This function is a limited implementation of objc_draw().  
  10588.                  It uses only VDI calls to render common GEM objects, so it
  10589.                  can be called from supervisor mode, or from within a
  10590.                  G_USERDEF drawing routine which the AES has called, without
  10591.                  the reentrancy problems encountered with the normal
  10592.                  objc_draw() function.
  10593.  
  10594.                  This function allows you to implement a G_USERDEF object
  10595.                  which is a conglomerate of standard GEM objects, without
  10596.                  needing to write custom rendering code.
  10597.  
  10598.                  These types of objects can be drawn by this function:
  10599.  
  10600.                      G_BOX       G_IBOX      G_BOXCHAR
  10601.                      G_TEXT      G_BOXTEXT
  10602.                      G_TITLE     G_STRING    G_RSTRING
  10603.                      G_BUTTON    G_USERDEF
  10604.  
  10605.                  The G_RSTRING object is a "replace string".  It is similar
  10606.                  to a G_BOXTEXT with no border; the new string completely
  10607.                  erases any existing string, even if the new string is
  10608.                  shorter.  The G_RSTRING type can only be used with this
  10609.                  function, objc_draw() can't handle it.
  10610.  
  10611.                  This function can also render the following object states:
  10612.  
  10613.                      SELECTED    OUTLINED    DISABLED
  10614.  
  10615.                  Other ob_state values are ignored.  The new TOS 4.x 3D
  10616.                  visual effects are NOT implemented by this function.
  10617.  
  10618.  
  10619.  
  10620.        
  10621.        ======================================================================
  10622.        GemFast v1.8                                                  Page 156
  10623.  
  10624.  
  10625.  
  10626.  
  10627.  
  10628.  
  10629.  
  10630.  
  10631.                  In my experience so far, extended objects tend to be made up
  10632.                  of BOX, BOXCHAR, TEXT, and STRING objects, and generally
  10633.                  only the SELECTED and DISABLED states are needed.
  10634.  
  10635.                  This function behaves exactly like objc_draw() in all
  10636.                  respects other than the limitation of objects and states it
  10637.                  can render.  IE, the HIDETREE flag is honored, and objects
  10638.                  and states are rendered in the same order as GEM does it.
  10639.  
  10640.                  While G_USERDEF is on the list, I have never tried to embed
  10641.                  a userdef object within another userdef object.  A nested
  10642.                  userdef object would have to be a passive one, at the very
  10643.                  least, at this point.
  10644.  
  10645.        Source:   aesfuncs\xob_draw.c
  10646.  
  10647.  
  10648.  
  10649.  
  10650.  
  10651.  
  10652.  
  10653.  
  10654.  
  10655.  
  10656.  
  10657.  
  10658.  
  10659.  
  10660.  
  10661.  
  10662.  
  10663.  
  10664.  
  10665.  
  10666.  
  10667.  
  10668.  
  10669.  
  10670.  
  10671.  
  10672.  
  10673.  
  10674.  
  10675.  
  10676.  
  10677.  
  10678.  
  10679.  
  10680.  
  10681.  
  10682.  
  10683.  
  10684.  
  10685.  
  10686.        
  10687.        ======================================================================
  10688.        GemFast v1.8                                                  Page 157
  10689.  
  10690.  
  10691.  
  10692.  
  10693.  
  10694.  
  10695.  
  10696.  
  10697.        void xob_transform(OBJECT *ptree, short object, XUSERBLK *pblk, 
  10698.                           XUB_DRAWFUNC *pdraw, XUB_TOUCHFUNC *ptouch,
  10699.                           long xub_size);
  10700.        ______________________________________________________________________
  10701.  
  10702.        Summary:  Transforms a system-defined object into a GemFast-defined
  10703.                  extended G_USERDEF object.
  10704.  
  10705.        Input:    The ptree parameter is a pointer to the object tree holding
  10706.                  the object to be transformed.
  10707.  
  10708.                  The object parameter is the index of the object which is to
  10709.                  be transformed.
  10710.  
  10711.                  The pblk parameter is a pointer to an XUSERBLK structure
  10712.                  that will be attached to the object by this function.
  10713.  
  10714.                  The pdraw parameter is a pointer to the function which
  10715.                  renders the object during objc_draw() processing.  This must
  10716.                  not be NULL.
  10717.  
  10718.                  The ptouch parameter is a pointer to the function which
  10719.                  handles clicks upon the object during dialog processing.  If
  10720.                  this is NULL, a passive object is created which does not
  10721.                  respond to clicks.
  10722.  
  10723.                  The xub_size parameter is the size of the data structure
  10724.                  pointed to by pblk.  If 0L is passed, sizeof(XUSERBLK) is
  10725.                  assumed internally.
  10726.  
  10727.        Returns:  Nothing.
  10728.  
  10729.        See Also:
  10730.  
  10731.        Details:  If you think up a new type of graphics object, or you want
  10732.                  to change the appearance of a standard object, GEM provides
  10733.                  the G_USERDEF object type to help you out.  With a G_USERDEF
  10734.                  object, the ob_spec field is a pointer to a USERBLK
  10735.                  structure.  The USERBLK contains a pointer to a function
  10736.                  that draws the object, and a 4-byte field containing
  10737.                  application-specific info.  When the AES is processing an
  10738.                  objc_draw() call, it calls your drawing function for any
  10739.                  G_USERDEF objects it finds.
  10740.  
  10741.                  If you want to transform a standard object into a G_USERDEF
  10742.                  object so that you can draw it differently, you have to
  10743.                  change the ob_type field and ob_spec field in the original
  10744.                  object -- six bytes of information.  But the USERBLK
  10745.                  structure gives you only four bytes to store application-
  10746.                  specific info, so you can't preserve both the original
  10747.                  ob_type and ob_spec in the USERBLK.
  10748.  
  10749.                  An XUSERBLK structure provides additional space for you to
  10750.                  store things in.  The first field is still a pointer to the
  10751.  
  10752.        
  10753.        ======================================================================
  10754.        GemFast v1.8                                                  Page 158
  10755.  
  10756.  
  10757.  
  10758.  
  10759.  
  10760.  
  10761.  
  10762.  
  10763.                  drawing routine, for GEM compatibility.  The second field
  10764.                  (where application data goes in a regular USERBLK) is a
  10765.                  pointer to the XUSERBLK itself.  The fact that the
  10766.                  application data field points back to the XUSERBLK itself is
  10767.                  the key used by GemFast internals to recognize a GemFast-
  10768.                  supported extended object.
  10769.  
  10770.                  To transform an object, allocate an XUSERBLK structure, and
  10771.                  call this function, passing pointers to the XUSERBLK, the
  10772.                  original object, and your custom drawing routine.  This
  10773.                  function copies the original object's ob_type and ob_spec
  10774.                  into the XUSERBLK. It then changes the original object's
  10775.                  ob_type and ob_spec, making it a G_USERDEF object.  It also
  10776.                  sets up the ub_code and ub_self fields of the XUSERBLK.  If
  10777.                  you want to store some of your own data in the XUSERBLK's
  10778.                  userflags or userdata fields, you can do so either before or
  10779.                  after calling this function; this function doesn't touch
  10780.                  those fields in the XUSERBLK.
  10781.  
  10782.                  If the original object has a non-zero value in the extended
  10783.                  object type (upper byte of ob_type), this function preserves
  10784.                  that info in the original object, and does not copy that
  10785.                  part of the ob_type to the XUSERBLK.
  10786.  
  10787.                  Other GemFast functions understand extended G_USERDEF
  10788.                  objects set up by this function.  For example, if you have a
  10789.                  button object, and you transform it into an extended
  10790.                  G_USERDEF so that it gets drawn differently, the pointer to
  10791.                  the button string is moved from the original ob_spec field
  10792.                  to the XUSERBLK structure.  But, the rsc_sstrings() and
  10793.                  rsc_gstrings() functions will still get or set the string
  10794.                  pointer correctly.  (IE, they'll work with the pointer in
  10795.                  the XUSERBLK rather than incorrectly disturbing the object's
  10796.                  ob_spec pointer.)
  10797.  
  10798.  
  10799.        Source:   aesfuncs\xobxform.c
  10800.  
  10801.  
  10802.  
  10803.  
  10804.  
  10805.  
  10806.  
  10807.  
  10808.  
  10809.  
  10810.  
  10811.  
  10812.  
  10813.  
  10814.  
  10815.  
  10816.  
  10817.  
  10818.        
  10819.        ======================================================================
  10820.        GemFast v1.8                                                  Page 159
  10821.  
  10822.  
  10823.  
  10824.  
  10825.